specs/external/shared/v0_2/accounts library

Classes

AccountBinding
Who may use an account, and how far. One binding per consumer per account. A binding is checked before anything is signed: the caller must be consumer, proven by the request's own proof; the request must sit inside scopeCeiling; its TTL must not exceed maxTtlSeconds; and the binding's rate must not be exhausted.
AccountProbeReport
AccountProbeReport
AccountProbeReportStepsItem
AccountProbeReportStepsItem, generated from its schema.
AccountPublicMaterial
The public half of the account's key, as the provider needs it. Never a private key.
AccountPublicMaterialPublicKeyJwk
The public key as a JWK, with kid. Public members only: the schema admits no private member (d, p, q, dp, dq, qi), so a document carrying one fails validation.
AccountSecretInfo
That a static model's secret is set, and which one. Never its value.
AccountSetupArtifacts
What an administrator does at the provider to make an account usable, generated by the custodian from the account's settings, public material and bindings. Public material and policy only: never a private key or secret, and the custodian never asks for the provider's administrator credentials.
AccountSetupArtifactsArtifactsItem
AccountSetupArtifactsArtifactsItem, generated from its schema.
AccountSetupArtifactsStepsItem
AccountSetupArtifactsStepsItem, generated from its schema.
CredentialScope
What one issuance may do. For storage models, prefix and actions (both required, a rule this schema leaves to the custodian because other models use neither); for s3-static-presign, also objectKey, since a presigned URL is one operation on one object; for oauth2-private-key-jwt, scopes.
CredentialScopeCeiling
The widest scope a binding's consumer may request. An issuance is inside the ceiling when its prefix begins with one of prefixes, every one of its actions is in actions, and every one of its scopes is in scopes. Absent members confer nothing: a ceiling with no prefixes permits no storage issuance.
ExternalAccount
An account as every read returns it. Contains no private key, no secret and no issued credential, to any reader.
ExternalSecretPayload
The cleartext inside the sealed bundle of external/accounts/secret/set. It names the account it is for, inside the seal, so that a bundle captured on its way to one account cannot be replayed into another: the custodian MUST refuse a bundle whose context or account differs from the request's. Never appears on the wire outside a seal.
PresignedRequestSet
The cleartext inside the sealed bundle of external/credentials/issue 0.2 and later for an s3-static-presign account: one presigned request per requested operation, all on one object, in the order requested. Never appears on the wire outside a seal, and a consumer keeps it in memory only and never logs a URL from it. Each request is a bearer credential until it expires: whoever holds it may make that one request, and nothing else.
PresignedRequestSetRequestsItem
PresignedRequestSetRequestsItem, generated from its schema.
SuiMoveCall
One Move function an account's transactions may call.

Extension Types

AccountProbeStep
sign: the custodian signed its assertion, session request or test transaction. exchange: the provider issued a credential for it. put, get, delete: one canary object at the narrowest scope of the account's bindings. decode: for sui-signer, a built test transaction passed the allow-list (it is never submitted).
AccountPublicMaterialAlgorithm
AccountPublicMaterialAlgorithm is a closed set of string values defined by this specification's schema.
AccountPublicMaterialPublicKeyJwkAlg
AccountPublicMaterialPublicKeyJwkAlg is a closed set of string values defined by this specification's schema.
AccountPublicMaterialPublicKeyJwkCrv
AccountPublicMaterialPublicKeyJwkCrv is a closed set of string values defined by this specification's schema.
AccountPublicMaterialPublicKeyJwkKty
AccountPublicMaterialPublicKeyJwkKty is a closed set of string values defined by this specification's schema.
AccountState
active: usable by its bindings. suspended: every issuance and signature is refused at once; management reads continue; resumable. archived: hidden from default listings, refused for use, restorable. Deletion removes the record.
AuthModel
How the account authenticates to its provider. Every model pins the custodian's verification material in the provider's own account, uploaded once, so no model requires the custodian to be reachable from the internet. aws-roles-anywhere: the custodian is the certificate authority of an IAM Roles Anywhere trust anchor, and signs CreateSession with a short-lived end-entity certificate it issued to the account's own key. gcp-wif-pinned: a Workload Identity Federation pool provider holds an uploaded JWKS; the custodian signs an ID token and exchanges it at Google's STS. azure-cert: a certificate uploaded to an Entra app registration; the custodian signs an RFC 7523 client assertion. oauth2-private-key-jwt: the same RFC 7523 client authentication against any token endpoint that registered the custodian's public key. s3-static-presign: an access-key pair for an S3-compatible store that cannot federate; the custodian presigns per-object URLs and never releases the key. sui-signer: a Sui address derived from the custodian's key; the custodian signs only allow-listed transactions. static-secret: an API key or token used inside the custodian by a named driver; last resort, never released. Plain OpenID Connect discovery federation is deliberately absent. It works by the provider fetching the issuer's JWKS from a public URL, which either makes the custodian reachable from the internet or makes whoever hosts a copy of the JWKS able to mint credentials for every federated role.
PresignedRequestSetRequestsItemMethod
The HTTP method the signature covers: GET for get and list-parts, HEAD for head, PUT for put and upload-part, POST for create-multipart and complete-multipart, DELETE for delete and abort-multipart.
PresignOperation
One S3 request a custodian presigns for an s3-static-presign account (external/credentials/issue 0.2 and later). Each is authorized by one ProviderObjectAction in the binding's ceiling, so the ceiling's vocabulary stays what can happen to an object rather than how the protocol does it: put (PutObject), create-multipart (CreateMultipartUpload), upload-part (UploadPart), list-parts (ListParts) and complete-multipart (CompleteMultipartUpload) need put; get (GetObject) and head (HeadObject) need get; delete (DeleteObject) and abort-multipart (AbortMultipartUpload) need delete, because each destroys bytes storage holds.
ProviderObjectAction
put: write an object. get: read one. delete: remove one. No list, ACL, policy or bucket-level action exists here, so none can be granted.

Typedefs

AccountContextId = String
The custodian context that owns the account. Act scope in this context decides who may manage the account and who may consume it; the account's keys are derived in this context's key space.
AccountId = String
The account's identifier within its context, chosen by whoever creates it. Lowercase letters, digits and hyphens, so that it can be embedded in a certificate subject, a token subject or a provider-side condition without escaping. Unique per context; never reused after deletion while anything that names it (a provider-side trust policy, an audit row) may still exist.
AccountSettings = Object?
Per-model account settings, discriminated by model: every branch is an object whose model member is a const, which is what lets each generated binding emit a tagged union, so an unusable setting is answered as external:invalidSettings naming the member rather than as an unparseable payload. Never a secret: every value here is returned to anyone who may read the account. Branches are referred to by their model ("the sui-signer settings"). They carry no title, so that every binding renders each as a plain variant of this union.
AwsArn = String
AwsArn, defined by this specification's schema.
AwsRegion = String
AwsRegion, defined by this specification's schema.
DigestMultibase = String
A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for digestMultibase, and the one did:webvh uses for its SCID and entry hashes. Multihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a sha-256:-style prefix hard-codes one algorithm into the wire contract and is non-conforming here. This definition constrains the encoding only. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible. Restricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — z (base58btc) and u (base64url-no-pad). CID permits others but states that "interoperability is not guaranteed between implementations using such values", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with did:key and did:webvh.
ExternalCredentialPayload = Object?
The cleartext inside the sealed bundle of external/credentials/issue, discriminated by kind. Never appears on the wire outside a seal, and a consumer keeps it in memory only.
ProviderBucketName = String
A bucket name as S3 and GCS accept it. Validated rather than free so that it can be placed in a provider policy without escaping.
ProviderHttpsUrl = String
ProviderHttpsUrl, defined by this specification's schema.
ProviderObjectPrefix = String
An object-key prefix within the account's bucket: one or more segments of lowercase letters, digits, ., _ and -, each beginning with a letter or digit and ending with /. No quote, backslash, wildcard, whitespace, .. segment or empty segment can appear. That is deliberate: the custodian places this value inside a provider policy — an IAM session policy (JSON), a GCS Credential Access Boundary condition (CEL) — and a value able to carry a metacharacter can break out of the string it is placed in and widen the policy. That is a known class of defect (CVE-2026-42811, a CEL injection in downscoped GCS credentials). Even with this pattern, a custodian MUST build provider policies with the provider language's own encoder, never by string interpolation.
SealedTransferBundle = String
A sealed-transfer bundle: OpenPGP-style ASCII armor around an HPKE-sealed SealedPayloadV1 (base mode, X25519-HKDF-SHA256 KEM, HKDF-SHA256 KDF, ChaCha20-Poly1305 AEAD, info string vta-sealed-transfer/v1), with a producer assertion and Bundle-Id, Chunk and Digest-Algo headers bound into the associated data. Each task states the key it is sealed to: a single-use wrapping key from keys/import-wrapping-key for external/accounts/secret/set, and the caller's key-agreement key for external/credentials/issue. Its cleartext is an ExternalSecretPayload, an ExternalCredentialPayload or, from external/credentials/issue 0.2 for s3-static-presign, a PresignedRequestSet. The only form in which secret material crosses the wire in this family, in either direction: the seal is what keeps a terminating proxy, a relay, a request log or a debug dump of "the response" from ever holding a usable secret, whatever transport carried the document.
SecretFingerprint = String
Which secret is set, without being a way to test guesses at it. hmacsha256: followed by the base64url encoding, without padding, of the first 16 bytes of HMAC-SHA256 over the secret's bytes under a fingerprint key the custodian holds and never discloses. Comparable only between fingerprints made by the same custodian: a re-entered value can be confirmed, while the same secret at two custodians gives unrelated fingerprints. Never a bare hash of the secret, which would let anyone who reads it run a dictionary against it offline; and deliberately not a DigestMultibase, since multihash has no code for a keyed digest.