docs(api): cut comments to what the code cannot say

Comments carry the mechanism, not the rationale; every argument removed
here is in the design proposal or the PR. Where one claim appeared at
several sites, the copy at the site that constrains the code stays.

Assisted-by: LLM
Signed-off-by: Timofei Larkin <lllamnyp@gmail.com>
This commit is contained in:
Timofei Larkin authored and IvanHunters committed 2026-11-17 12:07:14 +03:00
1 parent 5b86018cb0
commit c96b91f67a
17 files changed
+58 -99

No files matched your search

@@ -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"
)
+1 -2
View File
@@ -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"`
}
@@ -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 == "" {
@@ -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: |-
@@ -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
@@ -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:
+5 -10
View File
@@ -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"`
+2 -4
View File
@@ -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
+2 -3
View File
@@ -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"`
}
+2 -3
View File
@@ -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
+5 -11
View File
@@ -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[:])
+3 -5
View File
@@ -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"
+2 -4
View File
@@ -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
+12 -17
View File
@@ -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
// <valuesPath>.<DigestKey>. 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 <valuesPath>.<DigestKey>. 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 == "" {
@@ -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": {
@@ -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)
}
+6 -9
View File
@@ -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)