mirror of
https://github.com/cozystack/cozystack.git
synced 2026-11-21 12:13:55 +09:00
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:
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"
|
||||
)
|
||||
|
||||
|
||||
@@ -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 == "" {
|
||||
|
||||
+1
-3
@@ -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:
|
||||
|
||||
@@ -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"`
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"`
|
||||
}
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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[:])
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in new issue
Block a user