diff --git a/api/v1alpha1/applicationdefinition_credentials_types.go b/api/v1alpha1/applicationdefinition_credentials_types.go index dce23ed2f..4d3e9b19a 100644 --- a/api/v1alpha1/applicationdefinition_credentials_types.go +++ b/api/v1alpha1/applicationdefinition_credentials_types.go @@ -21,11 +21,8 @@ import ( ) // ApplicationDefinitionCredentials declares the accounts of an application -// kind and how the Cozystack API stores their passwords. Its presence is what -// converts the kind: the API seeds one account Secret per account when an -// application is written, serves a core.cozystack.io Credential per account, -// and mints a password on request. The chart renders only references to the -// account Secrets and never a password. See +// kind and how the Cozystack API stores their passwords. Its presence converts +// the kind to platform-minted credentials. See // design-proposals/user-secrets-api in cozystack/community. type ApplicationDefinitionCredentials struct { // Format is how a password is stored in the account Secret: the verifier the @@ -62,8 +59,7 @@ const ( // CredentialFormatBuiltIn names a function compiled into the API. CredentialFormatBuiltIn CredentialFormatKind = "BuiltIn" // CredentialFormatWebhook names an endpoint the API calls with the - // plaintext. Declared so a block can carry it without a schema change; the - // API refuses to serve a kind that uses it until the call is implemented. + // plaintext. Declared, not served yet. CredentialFormatWebhook CredentialFormatKind = "Webhook" ) diff --git a/api/v1alpha1/applicationdefinitions_types.go b/api/v1alpha1/applicationdefinitions_types.go index c08a0df6a..62969257c 100644 --- a/api/v1alpha1/applicationdefinitions_types.go +++ b/api/v1alpha1/applicationdefinitions_types.go @@ -62,8 +62,7 @@ type ApplicationDefinitionSpec struct { // Dashboard configuration for this resource Dashboard *ApplicationDefinitionDashboard `json:"dashboard,omitempty"` - // Credentials declares the kind's accounts and how the API stores their - // passwords. Its presence converts the kind to platform-minted credentials. + // Credentials converts the kind to platform-minted credentials. // +optional Credentials *ApplicationDefinitionCredentials `json:"credentials,omitempty"` } diff --git a/internal/controller/applicationdefinition_helmreconciler.go b/internal/controller/applicationdefinition_helmreconciler.go index 86d300839..e8461b3e2 100644 --- a/internal/controller/applicationdefinition_helmreconciler.go +++ b/internal/controller/applicationdefinition_helmreconciler.go @@ -159,13 +159,11 @@ func expectedValuesFrom() []helmv2.ValuesReference { return store.ValuesFrom(nil, "", nil) } -// releaseValuesFrom returns the valuesFrom a release should carry under its -// definition: the platform values, and for a kind whose block names a -// valuesPath one entry per account, so a release created before the block -// appeared gets the entries on its next reconcile. The accounts are resolved -// from the release's values with the definition's schema defaults applied, -// as the API resolves them on a write. An error means the values declare -// accounts the API would refuse, and leaves the release as it is. +// releaseValuesFrom returns the valuesFrom a release carries under its +// definition, resolving the accounts with the definition's schema defaults as +// the API does on a write, so a release created before the block appeared +// gets its entries on reconcile. An error means values the API would refuse; +// the release is left as it is. func releaseValuesFrom(hr *helmv2.HelmRelease, appDef *cozyv1alpha1.ApplicationDefinition) ([]helmv2.ValuesReference, error) { block := appDef.Spec.Credentials if block == nil || block.ValuesPath == "" { diff --git a/packages/system/application-definition-crd/definition/cozystack.io_applicationdefinitions.yaml b/packages/system/application-definition-crd/definition/cozystack.io_applicationdefinitions.yaml index 7ef569dd4..62108cc19 100644 --- a/packages/system/application-definition-crd/definition/cozystack.io_applicationdefinitions.yaml +++ b/packages/system/application-definition-crd/definition/cozystack.io_applicationdefinitions.yaml @@ -63,9 +63,7 @@ spec: - singular type: object credentials: - description: |- - Credentials declares the kind's accounts and how the API stores their - passwords. Its presence converts the kind to platform-minted credentials. + description: Credentials converts the kind to platform-minted credentials. properties: accounts: description: |- diff --git a/packages/system/cozystack-basics/templates/clusterroles.yaml b/packages/system/cozystack-basics/templates/clusterroles.yaml index 914ab5f5c..a142a3934 100644 --- a/packages/system/cozystack-basics/templates/clusterroles.yaml +++ b/packages/system/cozystack-basics/templates/clusterroles.yaml @@ -322,7 +322,7 @@ rules: - patch - delete # A mint replaces an account's password and shows the new one once, so it is -# an admin's write, not a reader's; a custom role can grant revoke alone. +# an admin's write, not a reader's. - apiGroups: ["core.cozystack.io"] resources: - credentials/mint diff --git a/packages/system/cozystack-basics/tests/clusterroles-credentials_test.yaml b/packages/system/cozystack-basics/tests/clusterroles-credentials_test.yaml index bf6d5c801..d40bba152 100644 --- a/packages/system/cozystack-basics/tests/clusterroles-credentials_test.yaml +++ b/packages/system/cozystack-basics/tests/clusterroles-credentials_test.yaml @@ -7,12 +7,10 @@ release: name: cozystack-basics namespace: cozy-system -# A Credential is the view of one managed application account, and a mint on -# it replaces the password and shows the new one once. Reading the view is a -# view-tier grant; minting and revoking are admin writes, and the tenant -# ServiceAccount, which the dashboard signs in with when OIDC is off, holds -# both. The subresources are gated by verb create on their own resource -# names, so a grant on credentials alone issues nothing. +# Reading a Credential is a view-tier grant; minting and revoking are admin +# writes, and the tenant ServiceAccount holds both. The subresources are gated +# by verb create on their own resource names, so a grant on credentials alone +# issues nothing. tests: - it: cozy:tenant:view:base grants read on core.cozystack.io credentials documentSelector: diff --git a/pkg/apis/core/v1alpha1/credential_types.go b/pkg/apis/core/v1alpha1/credential_types.go index 1283435f1..01dfc5614 100644 --- a/pkg/apis/core/v1alpha1/credential_types.go +++ b/pkg/apis/core/v1alpha1/credential_types.go @@ -1,19 +1,15 @@ // SPDX-License-Identifier: Apache-2.0 -// Credential is the account record of one platform-generated credential of a -// managed application: who can know the live password and who changed it. It -// is a view over the account Secret the Cozystack API keeps per account, and -// it never carries the password or the stored verifier. The password is -// obtained once, through the mint subresource, and replaced through it. See -// design-proposals/user-secrets-api in cozystack/community. - package v1alpha1 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object -// Credential is one account of a converted application. +// Credential is the record of one account of a converted application: who can +// know the live password and who changed it, never the password or its stored +// form. It is a view over the account Secret the API keeps. See +// design-proposals/user-secrets-api in cozystack/community. type Credential struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -105,8 +101,7 @@ type CredentialList struct { // CredentialRequest is the body and the answer of the mint and revoke // subresources of a Credential, in the shape of a Kubernetes TokenRequest: a // create on the subresource carries the request in spec and is answered with -// the result in status, and nothing is stored. The password in a mint's answer -// is the only place it ever exists outside the API's memory. +// the result in status, and nothing is stored. type CredentialRequest struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` diff --git a/pkg/cmd/server/start.go b/pkg/cmd/server/start.go index a92ee21c3..ad921c1a2 100644 --- a/pkg/cmd/server/start.go +++ b/pkg/cmd/server/start.go @@ -289,10 +289,8 @@ func resourceConfigFrom(defs []v1alpha1.ApplicationDefinition, hrFlags helmRelea } resourceConfig := &config.ResourceConfig{} for _, crd := range owned { - // A credentials block the API cannot honour, declaring a format or a - // source kind that is not built or a format it does not know, leaves - // the kind unserved rather than served with passwords it cannot - // issue, as a kind with an invalid name schema refuses writes. + // A block the API cannot honour leaves the kind unserved; see + // account.Validate. if err := account.Validate(crd.Spec.Credentials); err != nil { fmt.Printf("Skipping ApplicationDefinition %q: credentials block cannot be served: %v\n", crd.Name, err) continue diff --git a/pkg/config/config.go b/pkg/config/config.go index 5d743365f..3f004177b 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -197,9 +197,8 @@ type ResourceConfig struct { type Resource struct { Application ApplicationConfig `yaml:"application"` Release ReleaseConfig `yaml:"release"` - // Credentials is the kind's credentials block, copied from - // spec.credentials of its ApplicationDefinition at start-up. nil for a - // kind that is not converted to platform-minted credentials. + // Credentials is the definition's spec.credentials; nil for a kind that is + // not converted. Credentials *v1alpha1.ApplicationDefinitionCredentials `yaml:"credentials,omitempty"` } diff --git a/pkg/credentials/account/account.go b/pkg/credentials/account/account.go index 00f0a3269..cefbf2b59 100644 --- a/pkg/credentials/account/account.go +++ b/pkg/credentials/account/account.go @@ -92,10 +92,9 @@ func SplitCredentialName(name string) (release, mapped string, ok bool) { return release, mapped, true } -// Validate reports whether the API can serve a kind with this block. A format +// Validate reports whether the API can serve a kind with this block: a format // or a source kind that is declared but not built, an unknown built-in format, -// or a source missing the field its kind needs, refuses the whole kind, as a -// kind with an invalid name schema is refused today. +// or a source missing the field its kind needs, refuses the whole kind. func Validate(c *cozyv1alpha1.ApplicationDefinitionCredentials) error { if c == nil { return nil diff --git a/pkg/credentials/format/format.go b/pkg/credentials/format/format.go index ec925baaa..7f7592cac 100644 --- a/pkg/credentials/format/format.go +++ b/pkg/credentials/format/format.go @@ -1,10 +1,8 @@ // SPDX-License-Identifier: Apache-2.0 // Package format turns a password into the value an engine stores to check -// it, and generates the passwords. It knows formats and no engines: a kind -// names one of these in the credentials block of its ApplicationDefinition, -// and the migration tooling imports the same functions, so the API and the -// migration write the same bytes. +// it, and generates the passwords. The migration tooling imports it too, so a +// migrated release and a mint store the same form. package format import ( @@ -95,9 +93,7 @@ func Encode(name, password string) (string, error) { case MySQLNative: return encodeMySQLNative(password), nil case SHA256: - // Unsalted by the engine's choice: ClickHouse checks a login against - // password_sha256_hex and accepts no other form. The 32-character - // random password behind it is what makes the digest safe to store. + // Unsalted: ClickHouse's password_sha256_hex accepts no other form. sum := sha256.Sum256([]byte(password)) return hex.EncodeToString(sum[:]), nil case Plaintext: @@ -133,10 +129,8 @@ func hmacSHA256(key []byte, message string) []byte { return mac.Sum(nil) } -// encodeMySQLNative is MariaDB's PASSWORD(): SHA-1 of SHA-1, unsalted, which -// the mysql_native_password plugin stores and checks against and accepts in no -// other form. The 32-character random password behind it is what makes the -// digest safe to store. +// encodeMySQLNative is MariaDB's PASSWORD(): SHA-1 of SHA-1, unsalted, the +// only form mysql_native_password accepts. func encodeMySQLNative(password string) string { first := sha1.Sum([]byte(password)) second := sha1.Sum(first[:]) diff --git a/pkg/credentials/store/event.go b/pkg/credentials/store/event.go index f0089535e..482532091 100644 --- a/pkg/credentials/store/event.go +++ b/pkg/credentials/store/event.go @@ -22,11 +22,9 @@ const ( ReasonCredentialRevoked = "CredentialRevoked" ) -// Emit records an Event on the application, named through the HelmRelease -// that backs it, saying which account was issued or revoked and by whom. It -// never carries a value. Events are best effort: a failure to record one is -// logged and does not fail the operation it describes, which the audit log -// records in any case. +// Emit records an Event on the application naming the account and the caller, +// never a value. Best effort: a failure is logged and does not fail the +// operation, which the audit log records in any case. func Emit(ctx context.Context, c client.Client, hr *helmv2.HelmRelease, reason, username, by string) { now := metav1.NewTime(time.Now()) verb := "issued" diff --git a/pkg/credentials/store/resolve.go b/pkg/credentials/store/resolve.go index 4125a0735..980c321f1 100644 --- a/pkg/credentials/store/resolve.go +++ b/pkg/credentials/store/resolve.go @@ -15,11 +15,9 @@ import ( ) // ResolveAccounts resolves the tenant accounts an application declares from -// its values with the kind's schema defaults applied. Stored values carry no +// its values with the kind's schema defaults applied: stored values carry no // defaults, and a Static account switched on by a defaulted flag would -// otherwise go unseeded. The API resolves accounts this way on every write, -// and the ApplicationDefinition reconciler when it brings a release's -// valuesFrom in line with its definition. +// otherwise go unseeded. func ResolveAccounts(block *cozyv1alpha1.ApplicationDefinitionCredentials, schema *structuralschema.Structural, values *apiextv1.JSON) ([]account.Account, error) { if block == nil { return nil, nil diff --git a/pkg/credentials/store/store.go b/pkg/credentials/store/store.go index bd2441e9d..95a83a339 100644 --- a/pkg/credentials/store/store.go +++ b/pkg/credentials/store/store.go @@ -1,11 +1,9 @@ // SPDX-License-Identifier: Apache-2.0 -// Package store writes and removes account Secrets for the Cozystack API: it -// seeds one per account when an application is written, prunes the ones a -// write removes, and builds the valuesFrom entries that carry a stored value -// into a chart whose operator cannot read a Secret. The mint itself lives in -// the credential registry; this package is what the application registry -// needs around a HelmRelease write. +// Package store writes and removes account Secrets around a HelmRelease write: +// it seeds one per account, prunes the ones a write removes, and builds the +// valuesFrom entries that carry a stored value into a chart whose operator +// cannot read a Secret. package store import ( @@ -88,11 +86,10 @@ func SeedSecret(app App, acc account.Account, owner *metav1.OwnerReference, now } // Theirs reports whether an existing Secret is the application's own account -// Secret for the account: it carries the account marker, holds the same -// username, and is owned by the live HelmRelease. On a create no HelmRelease -// exists yet, so a Secret that any HelmRelease owns is left over from a -// deleted application of the same name and is replaced, so the account gets a -// new identity, while one nobody owns is from a create that did not finish. +// Secret: marker, same username, owned by the live HelmRelease. With no +// HelmRelease yet (a create), one any HelmRelease owns is left from a deleted +// application of the same name and is replaced, so the account gets a new +// identity; one nobody owns is from a create that did not finish. func Theirs(sec *corev1.Secret, acc account.Account, owner *metav1.OwnerReference) bool { if !account.IsAccountSecret(sec) || string(sec.Data[account.UsernameKey]) != acc.Username { return false @@ -214,12 +211,10 @@ func DigestKey(username string) string { return "u" + hex.EncodeToString(sum[:]) } -// ValuesFrom returns the HelmRelease valuesFrom entries of an application: -// the platform values first, as every release has them, then one entry per -// account for a kind with a valuesPath, reading the Secret's stored value into -// .. The API and the ApplicationDefinition reconciler -// both build the list here, so a release created before the block appeared -// gets the same entries on its next reconcile. +// ValuesFrom returns the HelmRelease valuesFrom entries of an application: the +// platform values, then for a kind with a valuesPath one entry per account +// reading the Secret's stored value into .. The API and +// the ApplicationDefinition reconciler must build the same list. func ValuesFrom(block *cozyv1alpha1.ApplicationDefinitionCredentials, release string, accounts []account.Account) []helmv2.ValuesReference { refs := []helmv2.ValuesReference{{Kind: "Secret", Name: "cozystack-values"}} if block == nil || block.ValuesPath == "" { diff --git a/pkg/generated/openapi/zz_generated.openapi.go b/pkg/generated/openapi/zz_generated.openapi.go index 2af8e2e36..31310c405 100644 --- a/pkg/generated/openapi/zz_generated.openapi.go +++ b/pkg/generated/openapi/zz_generated.openapi.go @@ -334,7 +334,7 @@ func schema_pkg_apis_core_v1alpha1_Credential(ref common.ReferenceCallback) comm return common.OpenAPIDefinition{ Schema: spec.Schema{ SchemaProps: spec.SchemaProps{ - Description: "Credential is one account of a converted application.", + Description: "Credential is the record of one account of a converted application: who can know the live password and who changed it, never the password or its stored form. It is a view over the account Secret the API keeps. See design-proposals/user-secrets-api in cozystack/community.", Type: []string{"object"}, Properties: map[string]spec.Schema{ "kind": { @@ -531,7 +531,7 @@ func schema_pkg_apis_core_v1alpha1_CredentialRequest(ref common.ReferenceCallbac return common.OpenAPIDefinition{ Schema: spec.Schema{ SchemaProps: spec.SchemaProps{ - Description: "CredentialRequest is the body and the answer of the mint and revoke subresources of a Credential, in the shape of a Kubernetes TokenRequest: a create on the subresource carries the request in spec and is answered with the result in status, and nothing is stored. The password in a mint's answer is the only place it ever exists outside the API's memory.", + Description: "CredentialRequest is the body and the answer of the mint and revoke subresources of a Credential, in the shape of a Kubernetes TokenRequest: a create on the subresource carries the request in spec and is answered with the result in status, and nothing is stored.", Type: []string{"object"}, Properties: map[string]spec.Schema{ "kind": { diff --git a/pkg/registry/apps/application/rest_credentials.go b/pkg/registry/apps/application/rest_credentials.go index d9fd02230..4ae281fcd 100644 --- a/pkg/registry/apps/application/rest_credentials.go +++ b/pkg/registry/apps/application/rest_credentials.go @@ -29,11 +29,8 @@ func (r *REST) Credentials() *cozyv1alpha1.ApplicationDefinitionCredentials { return r.credentials } -// AccountsOf resolves the tenant accounts a HelmRelease declares, from its -// values with the kind's schema defaults applied. The stored values carry no -// defaults, and a Static account switched on by a defaulted flag would -// otherwise go unseeded. It is what the credentials registry asks on a mint of -// an account whose Secret is missing. +// AccountsOf resolves the tenant accounts a HelmRelease declares; the +// credentials registry asks it on a mint of an account whose Secret is missing. func (r *REST) AccountsOf(_ context.Context, hr *helmv2.HelmRelease) ([]account.Account, error) { return r.accountsOf(hr.Spec.Values) } diff --git a/pkg/registry/core/credential/rest.go b/pkg/registry/core/credential/rest.go index d809f78af..f09c43cf7 100644 --- a/pkg/registry/core/credential/rest.go +++ b/pkg/registry/core/credential/rest.go @@ -1,11 +1,9 @@ // SPDX-License-Identifier: Apache-2.0 -// Package credential serves core.cozystack.io/credentials: a view over the -// account Secrets the Cozystack API writes for the accounts of converted -// applications, with the mint and revoke subresources that are the only way -// to obtain or retire a password. The view shows the account's record and -// never the Secret's data. See design-proposals/user-secrets-api in -// cozystack/community. +// Package credential serves core.cozystack.io/credentials, a view over the +// account Secrets the API writes, with the mint and revoke subresources. The +// view shows the account's record and never the Secret's data. See +// design-proposals/user-secrets-api in cozystack/community. package credential import ( @@ -53,9 +51,8 @@ const ( ) // Kind is what the registry knows about one converted application kind: its -// credentials block, and how to resolve the accounts an application declares -// from the values its HelmRelease carries, which the application registry -// does with the kind's schema defaults applied. +// credentials block, and how to resolve the accounts a HelmRelease declares, +// which the application registry does with the kind's schema defaults. type Kind struct { Block *cozyv1alpha1.ApplicationDefinitionCredentials Accounts func(ctx context.Context, hr *helmv2.HelmRelease) ([]account.Account, error)