Files
iam/internal/keys/zipdoc_gen.go
zeekay 5c067f1791 keys: a member lists the keys they hold in their org
The key collection now authorizes itself.  A person names an org they
belong to: its admin, or a SuperAdmin, reads every key it holds, and
anyone else reads the keys they hold there.  A stranger is refused with
the bytes every stranger gets, and a reserved org's keys stay a
SuperAdmin's alone.  A confidential client still needs key-mint and
still reads only the org it serves, so its credential alone never reads
another tenant's keys.  A named key stays the Guard's.

The allowlist lookup moves to the principal leaf, so a collection that
authentication is built on asks a capability the way the Guard does.

Claude-Session: https://claude.ai/code/session_01HvACxex9ZZTzJCCHgirsGy
2026-10-06 20:14:00 -07:00

86 lines
17 KiB
Go

// Code generated by zipdoc; DO NOT EDIT.
package keys
import (
"github.com/zap-proto/zip"
)
func init() {
zip.Describe("github.com/hanzoai/iam/internal/keys DELETE /v1/iam/keys/:owner/:name", zip.Doc{
Description: "Revokes an API key. Anything still presenting it stops being authorized at\nonce, so roll the replacement out before you revoke.",
})
zip.Describe("github.com/hanzoai/iam/internal/keys GET /v1/iam/keys", zip.Doc{
Description: "Returns the API keys of an organization that you may see, newest first —\nwhat each is called, what it may reach, its publishable half, and when it was\nlast used. Secret halves are never listed.\n\nWhich keys come from your credentials, not from the request. You may name an\norganization you belong to: its admin sees every key it holds, and a member sees\nthe keys they hold there. Naming any other organization is refused.",
Fields: map[string]string{
"Key.accessKey": "AccessKey (pk-*) is the publishable identifier and lookup index;\nAccessSecret (sk-*) is the confidential secret.\nAccessSecret IS NOT PERSISTED for a key minted at or after the digest\nchange: it carries the secret out to its holder once, in the mint response,\nand the row keeps only AccessSecretDigest. It stays on the struct because\nthat one-time reveal is the whole point of minting, and it stays in the\nschema because rows written before the change still hold a plaintext secret\nthat the resolver drains on first use.",
"Key.accessSecretDigest": "AccessSecretDigest is how a presented secret finds its key: the resolver\ndigests what the caller sent and looks THAT up. It is what lets the row hold\nno plaintext and still be found in one indexed read — a salted hash cannot be\nlooked up by value, which is the reason the plaintext was here.",
"Key.act": "Act is the durable, opt-in grant that lets this key act FOR a user in its\nown org — the credential behind as(): presenting it authorizes minting a\nshort-lived, user-bound token for a member of the key's tenant. Default\nfalse, so a server key mints nothing on anyone's behalf until the grant is\nset deliberately — the capability is never inherited by every key. It is\nconfined at mint time to the key's OWN Owner, and a reserved-org or\nSuperAdmin target is refused, so the grant reaches only ordinary members of\nthe one tenant that holds the key.",
"Key.createdTime": "CreatedTime and UpdatedTime are RFC3339 audit stamps carried as strings\nfor byte-parity with the v1 row (orm.Model separately tracks CreatedAt /\nUpdatedAt as time.Time for the store's own lifecycle).",
"Key.displayName": "DisplayName is the human-facing label.",
"Key.expireTime": "ExpireTime is when the key stops being honored (empty = never). State is\nthe lifecycle flag (\"Active\", \"test\", …); \"test\" mints test-env\ncredentials instead of live ones.",
"Key.owner": "Owner is the tenant that holds the key; Name is unique within Owner.",
"Key.prefix": "Prefix is the head of the credential the holder presents — the sk- of a\nsecret key, the pk- of a publishable one — recorded when the key is minted\n(PrefixOf). It lets a listing say which string a row is, and is far too\nshort to use: the secret itself is never stored.",
"Key.revoker": "Revoker is who revoked the key and RevokeTime when. Revoking sets State to\nKeyStateRevoked and keeps the row, so the key is still listed and its\nhistory can be read; the resolvers refuse it, and no update reopens it.",
"Key.scope": "Scope is the key's ACCESS CLASS, orthogonal to Type (which names the bound\nprincipal). Empty (the default, \"secret\") is a full key: a pk- publishable\nhalf AND a confidential sk- half, the sk- authenticating a server-side reader.\nKeyScopePublish is a WRITE-ONLY publishable key — a pk- half only, no secret —\nthat resolves to just an ORG (never a principal) at the ingest endpoint and is safe\nto ship in client JS. A missing value on an existing row reads as the default,\nso every pre-Scope key is a secret key unchanged.",
"Key.type": "Type is the scope the key is bound to — \"Organization\", \"Application\",\n\"User\", or \"General\" — and Organization / Application / User name the\nconcrete principal for whichever scope Type selects.",
"Key.usedTime": "UsedTime is when the key was last presented and resolved. A list read fills\nit from the key's Sighting; the key row itself never holds it, so recording a\nuse never rewrites the row a person may be editing.",
"Model[github.com/hanzoai/iam/pkg/schema.Key].id": "Persisted fields",
},
})
zip.Describe("github.com/hanzoai/iam/internal/keys GET /v1/iam/keys/:owner/:name", zip.Doc{
Description: "Returns one API key: what it is called, what it may reach, and when it was\nissued.",
Fields: map[string]string{
"Key.accessKey": "AccessKey (pk-*) is the publishable identifier and lookup index;\nAccessSecret (sk-*) is the confidential secret.\nAccessSecret IS NOT PERSISTED for a key minted at or after the digest\nchange: it carries the secret out to its holder once, in the mint response,\nand the row keeps only AccessSecretDigest. It stays on the struct because\nthat one-time reveal is the whole point of minting, and it stays in the\nschema because rows written before the change still hold a plaintext secret\nthat the resolver drains on first use.",
"Key.accessSecretDigest": "AccessSecretDigest is how a presented secret finds its key: the resolver\ndigests what the caller sent and looks THAT up. It is what lets the row hold\nno plaintext and still be found in one indexed read — a salted hash cannot be\nlooked up by value, which is the reason the plaintext was here.",
"Key.act": "Act is the durable, opt-in grant that lets this key act FOR a user in its\nown org — the credential behind as(): presenting it authorizes minting a\nshort-lived, user-bound token for a member of the key's tenant. Default\nfalse, so a server key mints nothing on anyone's behalf until the grant is\nset deliberately — the capability is never inherited by every key. It is\nconfined at mint time to the key's OWN Owner, and a reserved-org or\nSuperAdmin target is refused, so the grant reaches only ordinary members of\nthe one tenant that holds the key.",
"Key.createdTime": "CreatedTime and UpdatedTime are RFC3339 audit stamps carried as strings\nfor byte-parity with the v1 row (orm.Model separately tracks CreatedAt /\nUpdatedAt as time.Time for the store's own lifecycle).",
"Key.displayName": "DisplayName is the human-facing label.",
"Key.expireTime": "ExpireTime is when the key stops being honored (empty = never). State is\nthe lifecycle flag (\"Active\", \"test\", …); \"test\" mints test-env\ncredentials instead of live ones.",
"Key.owner": "Owner is the tenant that holds the key; Name is unique within Owner.",
"Key.prefix": "Prefix is the head of the credential the holder presents — the sk- of a\nsecret key, the pk- of a publishable one — recorded when the key is minted\n(PrefixOf). It lets a listing say which string a row is, and is far too\nshort to use: the secret itself is never stored.",
"Key.revoker": "Revoker is who revoked the key and RevokeTime when. Revoking sets State to\nKeyStateRevoked and keeps the row, so the key is still listed and its\nhistory can be read; the resolvers refuse it, and no update reopens it.",
"Key.scope": "Scope is the key's ACCESS CLASS, orthogonal to Type (which names the bound\nprincipal). Empty (the default, \"secret\") is a full key: a pk- publishable\nhalf AND a confidential sk- half, the sk- authenticating a server-side reader.\nKeyScopePublish is a WRITE-ONLY publishable key — a pk- half only, no secret —\nthat resolves to just an ORG (never a principal) at the ingest endpoint and is safe\nto ship in client JS. A missing value on an existing row reads as the default,\nso every pre-Scope key is a secret key unchanged.",
"Key.type": "Type is the scope the key is bound to — \"Organization\", \"Application\",\n\"User\", or \"General\" — and Organization / Application / User name the\nconcrete principal for whichever scope Type selects.",
"Key.usedTime": "UsedTime is when the key was last presented and resolved. A list read fills\nit from the key's Sighting; the key row itself never holds it, so recording a\nuse never rewrites the row a person may be editing.",
"Model[github.com/hanzoai/iam/pkg/schema.Key].id": "Persisted fields",
},
})
zip.Describe("github.com/hanzoai/iam/internal/keys POST /v1/iam/keys", zip.Doc{
Description: "Issues an API key. A standard key comes back as a publishable half you\nmay ship in client code and a secret half you must not — the secret is shown\nonce, at creation, and cannot be retrieved afterwards. A publish-scoped key is\nissued with the publishable half only, so there is no secret to leak.\n\nA name already used in your organization is refused rather than reissued, so\ncreating twice never silently invalidates a key that is in production.\n\nA key you create is yours: it names you as its holder and speaks for you in the\norganization it is filed in. Naming anyone else as its holder is refused; a\nSuperAdmin names the person a key is for.",
Fields: map[string]string{
"Key.accessKey": "AccessKey (pk-*) is the publishable identifier and lookup index;\nAccessSecret (sk-*) is the confidential secret.\nAccessSecret IS NOT PERSISTED for a key minted at or after the digest\nchange: it carries the secret out to its holder once, in the mint response,\nand the row keeps only AccessSecretDigest. It stays on the struct because\nthat one-time reveal is the whole point of minting, and it stays in the\nschema because rows written before the change still hold a plaintext secret\nthat the resolver drains on first use.",
"Key.accessSecretDigest": "AccessSecretDigest is how a presented secret finds its key: the resolver\ndigests what the caller sent and looks THAT up. It is what lets the row hold\nno plaintext and still be found in one indexed read — a salted hash cannot be\nlooked up by value, which is the reason the plaintext was here.",
"Key.act": "Act is the durable, opt-in grant that lets this key act FOR a user in its\nown org — the credential behind as(): presenting it authorizes minting a\nshort-lived, user-bound token for a member of the key's tenant. Default\nfalse, so a server key mints nothing on anyone's behalf until the grant is\nset deliberately — the capability is never inherited by every key. It is\nconfined at mint time to the key's OWN Owner, and a reserved-org or\nSuperAdmin target is refused, so the grant reaches only ordinary members of\nthe one tenant that holds the key.",
"Key.createdTime": "CreatedTime and UpdatedTime are RFC3339 audit stamps carried as strings\nfor byte-parity with the v1 row (orm.Model separately tracks CreatedAt /\nUpdatedAt as time.Time for the store's own lifecycle).",
"Key.displayName": "DisplayName is the human-facing label.",
"Key.expireTime": "ExpireTime is when the key stops being honored (empty = never). State is\nthe lifecycle flag (\"Active\", \"test\", …); \"test\" mints test-env\ncredentials instead of live ones.",
"Key.owner": "Owner is the tenant that holds the key; Name is unique within Owner.",
"Key.prefix": "Prefix is the head of the credential the holder presents — the sk- of a\nsecret key, the pk- of a publishable one — recorded when the key is minted\n(PrefixOf). It lets a listing say which string a row is, and is far too\nshort to use: the secret itself is never stored.",
"Key.revoker": "Revoker is who revoked the key and RevokeTime when. Revoking sets State to\nKeyStateRevoked and keeps the row, so the key is still listed and its\nhistory can be read; the resolvers refuse it, and no update reopens it.",
"Key.scope": "Scope is the key's ACCESS CLASS, orthogonal to Type (which names the bound\nprincipal). Empty (the default, \"secret\") is a full key: a pk- publishable\nhalf AND a confidential sk- half, the sk- authenticating a server-side reader.\nKeyScopePublish is a WRITE-ONLY publishable key — a pk- half only, no secret —\nthat resolves to just an ORG (never a principal) at the ingest endpoint and is safe\nto ship in client JS. A missing value on an existing row reads as the default,\nso every pre-Scope key is a secret key unchanged.",
"Key.type": "Type is the scope the key is bound to — \"Organization\", \"Application\",\n\"User\", or \"General\" — and Organization / Application / User name the\nconcrete principal for whichever scope Type selects.",
"Key.usedTime": "UsedTime is when the key was last presented and resolved. A list read fills\nit from the key's Sighting; the key row itself never holds it, so recording a\nuse never rewrites the row a person may be editing.",
"Model[github.com/hanzoai/iam/pkg/schema.Key].id": "Persisted fields",
},
})
zip.Describe("github.com/hanzoai/iam/internal/keys PUT /v1/iam/keys/:owner/:name", zip.Doc{
Description: "Changes what a key is called, what it may reach, when it expires, or\nrevokes it. The credential itself is not reissued — the key in your deployment\nkeeps working until it expires or is revoked.\n\nAn update writes the whole set of editable fields, so send the key as you read\nit with your changes made. The class in its scope (publishable or secret) is\nfixed at creation and an update naming the other is refused. Setting state to\n\"Revoked\" revokes the key: the row stays, records who revoked it and when, and\nis never updated again.",
Fields: map[string]string{
"Key.accessKey": "AccessKey (pk-*) is the publishable identifier and lookup index;\nAccessSecret (sk-*) is the confidential secret.\nAccessSecret IS NOT PERSISTED for a key minted at or after the digest\nchange: it carries the secret out to its holder once, in the mint response,\nand the row keeps only AccessSecretDigest. It stays on the struct because\nthat one-time reveal is the whole point of minting, and it stays in the\nschema because rows written before the change still hold a plaintext secret\nthat the resolver drains on first use.",
"Key.accessSecretDigest": "AccessSecretDigest is how a presented secret finds its key: the resolver\ndigests what the caller sent and looks THAT up. It is what lets the row hold\nno plaintext and still be found in one indexed read — a salted hash cannot be\nlooked up by value, which is the reason the plaintext was here.",
"Key.act": "Act is the durable, opt-in grant that lets this key act FOR a user in its\nown org — the credential behind as(): presenting it authorizes minting a\nshort-lived, user-bound token for a member of the key's tenant. Default\nfalse, so a server key mints nothing on anyone's behalf until the grant is\nset deliberately — the capability is never inherited by every key. It is\nconfined at mint time to the key's OWN Owner, and a reserved-org or\nSuperAdmin target is refused, so the grant reaches only ordinary members of\nthe one tenant that holds the key.",
"Key.createdTime": "CreatedTime and UpdatedTime are RFC3339 audit stamps carried as strings\nfor byte-parity with the v1 row (orm.Model separately tracks CreatedAt /\nUpdatedAt as time.Time for the store's own lifecycle).",
"Key.displayName": "DisplayName is the human-facing label.",
"Key.expireTime": "ExpireTime is when the key stops being honored (empty = never). State is\nthe lifecycle flag (\"Active\", \"test\", …); \"test\" mints test-env\ncredentials instead of live ones.",
"Key.owner": "Owner is the tenant that holds the key; Name is unique within Owner.",
"Key.prefix": "Prefix is the head of the credential the holder presents — the sk- of a\nsecret key, the pk- of a publishable one — recorded when the key is minted\n(PrefixOf). It lets a listing say which string a row is, and is far too\nshort to use: the secret itself is never stored.",
"Key.revoker": "Revoker is who revoked the key and RevokeTime when. Revoking sets State to\nKeyStateRevoked and keeps the row, so the key is still listed and its\nhistory can be read; the resolvers refuse it, and no update reopens it.",
"Key.scope": "Scope is the key's ACCESS CLASS, orthogonal to Type (which names the bound\nprincipal). Empty (the default, \"secret\") is a full key: a pk- publishable\nhalf AND a confidential sk- half, the sk- authenticating a server-side reader.\nKeyScopePublish is a WRITE-ONLY publishable key — a pk- half only, no secret —\nthat resolves to just an ORG (never a principal) at the ingest endpoint and is safe\nto ship in client JS. A missing value on an existing row reads as the default,\nso every pre-Scope key is a secret key unchanged.",
"Key.type": "Type is the scope the key is bound to — \"Organization\", \"Application\",\n\"User\", or \"General\" — and Organization / Application / User name the\nconcrete principal for whichever scope Type selects.",
"Key.usedTime": "UsedTime is when the key was last presented and resolved. A list read fills\nit from the key's Sighting; the key row itself never holds it, so recording a\nuse never rewrites the row a person may be editing.",
"Model[github.com/hanzoai/iam/pkg/schema.Key].id": "Persisted fields",
},
})
}