capauth

type AttenuateParams struct {
	// NewHolder is the 32-byte hash of the wielder's public key the
	// child cap is for.
	NewHolder [32]byte

	// Permissions is the bitmask of operations to grant the child.
	// MUST be a subset of the parent's; cap.Attenuate intersects, so
	// passing 0xFFFF... is equivalent to "inherit all".
	Permissions uint64

	// Audience, if set, narrows the audience to a more specific
	// resource server. MUST equal the parent's audience or be the
	// child's own narrowing under the parent's. A child cap MAY add an
	// audience that the parent didn't carry (that's narrowing the
	// implicit "anyone" to "this one"), but a child MAY NOT change a
	// parent's existing audience to a different one. v1 enforces the
	// strict rule "audience may be added but never changed" — that's
	// the only safe option without a richer audience-hierarchy schema.
	Audience [32]byte

	// ExpiresAt, if non-zero, is the child's expiry. cap.Attenuate
	// floors this to the parent's; we additionally refuse to *raise*
	// it via the helper boundary so the caller's error is friendly.
	ExpiresAt int64

	// MaxDepth is the child's remaining-hops budget. 0 means "inherit
	// (parent's - 1)" if the parent carries a MaxDepth caveat, or
	// "unbounded by caveat" if the parent does not. A positive
	// MaxDepth that exceeds (parent's - 1) is ErrCaveatWidened.
	MaxDepth uint8

	// ExtraCaveats are caveats the caller wants to add beyond the
	// helper-managed kinds. Same duplicate-vs-helper rule as
	// IssueParams.
	ExtraCaveats []cap.Caveat
}

type Clock interface {
	Now() time.Time
}

type Ed25519Signer = ed25519Signer

type FixedClock struct{ T time.Time }

type IdentityCtx struct {
	// PrincipalHex is the lowercase-hex Hash32 of the holder pubkey
	// (or, in v1, the userID hash when the controller bound to the
	// signed-in principal instead of a device pubkey). Suitable for
	// logging, audit trails, and "who am I" responses.
	PrincipalHex string

	// ScopesBits is the cap's Permissions field. Handlers that need to
	// enforce per-route gating beyond what the middleware checked
	// inspect this bitmask.
	ScopesBits uint64

	// CapKind is the cap.CapKind the holder presented. Useful for
	// branching: a KindIAMSession cap shouldn't be doing KindKMSSign work.
	CapKind uint32

	// ChainDepth is len(chain)+1. v1 only accepts root caps (chain
	// length 0) so this is always 1 today; the field is present for
	// the day we allow attenuated caps at the edge.
	ChainDepth int

	// CapID is the cap's ID() — the SHA-256 of the wire bytes. Audit
	// trails MUST log this; on revocation it's the index key.
	CapID [32]byte
}

type IssueParams struct {
	// Kind is the CapKind from capabilities_kinds.md. Issuers MUST pass a
	// known kind; the cap runtime does not enforce a closed set, but
	// resource servers fail-closed on unknown kinds and so will Verify.
	Kind cap.CapKind

	// Target is the 32-byte BLAKE3 hash of the object this cap grants
	// over. The verifier compares this against the resource server's
	// notion of the target it serves; mismatch is ErrTargetMismatch.
	Target [32]byte

	// Holder is the 32-byte hash of the wielder's public key. The wire
	// format does not bind to the keypair unless the caller layers
	// proof-of-possession on top of this package (see CaveatBearerKey
	// note in capauth.go); v1 trusts possession of the cap bytes.
	Holder [32]byte

	// Permissions is the bitmask of operations this cap allows on
	// Target. See capabilities_kinds.md for per-Kind bit assignments.
	Permissions uint64

	// Audience, if non-zero, is the 32-byte hash of the resource server
	// this cap is intended for. Encoded as a CaveatAudience entry in the
	// minted cap. Verifiers reject when the cap's audience does not name
	// them.
	Audience [32]byte

	// NotBefore, if non-zero, is the Unix-seconds floor before which the
	// cap is not yet valid. Encoded as a CaveatNotBefore-style entry —
	// see the caveat-kind allocation note below.
	NotBefore int64

	// ExpiresAt, if non-zero, is the Unix-seconds expiry. Encoded both
	// in the cap's ExpiresAt field (for the runtime's fast-path check)
	// and as a CaveatExpiresAt entry (which the verifier ANDs over the
	// whole chain).
	ExpiresAt int64

	// MaxDepth, if non-zero, caps how many further attenuations this
	// cap may produce. Encoded as a CaveatMaxDepth entry.
	MaxDepth uint8

	// ExtraCaveats appends caveats the caller already knows about. The
	// helper-side rule is: helper-managed caveats (Audience, NotBefore,
	// ExpiresAt, MaxDepth) are emitted automatically and MUST NOT appear
	// in ExtraCaveats, or Issue returns ErrCaveatDuplicate.
	ExtraCaveats []cap.Caveat
}

type Issuer struct {
	// Signer is the cap.Signer that signs minted caps. Required.
	Signer cap.Signer
	// Scheme is the algorithm tag advertised in the cap.SigSize footer
	// (at byte cap.AlgTagOffset). The cap runtime writes the tag inside
	// the Signer.Sign call so the wire layer and the Issuer's typed
	// notion stay aligned: cap-aware callers can read back "what scheme
	// did this cap use" without re-parsing the signed bytes.
	Scheme Scheme
	// Clock supplies IssuedAt timestamps; defaults to SystemClock if nil.
	Clock Clock
}

type IssuerKeyDescriptor struct {
	// Scheme is the SchemeXxx value (1 = ed25519 today).
	Scheme uint8 `json:"scheme"`

	// FingerprintHex is the lowercase-hex Hash32 of the public-key bytes,
	// which is also what cap.Cap.Issuer() returns. Resource servers index
	// their registry by this hash.
	FingerprintHex string `json:"fingerprintHex"`

	// PublicKeyBase64 is the raw public-key bytes (32 for ed25519,
	// FIPS-204-canonical for ML-DSA-65) standard-base64 encoded.
	PublicKeyBase64 string `json:"publicKeyBase64"`

	// NotAfter, if non-zero, is the Unix-seconds at which this issuer key
	// is scheduled to retire — resource servers may then drop it from
	// their registry on next refresh. Zero means "no scheduled retirement".
	NotAfter int64 `json:"notAfter,omitempty"`
}

type IssuerRegistry interface {
	// Lookup returns the raw public-key bytes for the issuer whose
	// 32-byte hash is hashedPub. For ed25519, the returned bytes are
	// the 32-byte raw public key. For ML-DSA-65, the returned bytes
	// are the FIPS 204 canonical public-key encoding.
	//
	// Implementations must return cap.ErrIssuerUnknown for unknown
	// hashes — the cap runtime's Verifier.Verify is sensitive to this
	// specific sentinel.
	Lookup(hashedPub [32]byte) ([]byte, error)

	// Register associates a raw pubkey with its hash. Idempotent — a
	// repeated registration of the same (hash, pub) pair is a no-op;
	// a repeated registration with a different pub bytes panics (this
	// would indicate a hash collision, which is cryptographic-grade
	// unlikely and a sign of a broken hash function).
	Register(hashedPub [32]byte, pub []byte)
}

type KMSClient interface {
	// FetchEd25519Seed returns the 32-byte ed25519 seed at keyRef. NOT
	// the 64-byte expanded private key — KMS stores the seed; expansion
	// happens here, in-process, and the seed bytes are zeroed
	// immediately afterwards.
	FetchEd25519Seed(keyRef string) ([]byte, error)

	// FetchMLDSA65Private returns the canonical FIPS 204 private-key
	// encoding at keyRef. The bytes are unmarshalled in-process and the
	// raw buffer zeroed.
	FetchMLDSA65Private(keyRef string) ([]byte, error)
}

type LibVerifier struct {
	// Store backs the IsRevoked check. Nil means "treat everything as
	// non-revoked" (only sane in tests).
	Store RevocationStore

	// Registry resolves issuer hashes to raw public-key bytes. Nil is a
	// configuration error and Verify returns ErrIssuerUnknown.
	Registry IssuerRegistry

	// Clock supplies the current time for expiry checks. Defaults to
	// SystemClock if nil.
	Clock Clock

	// Identity is the 32-byte hash of THIS resource server's public
	// identity. Compared in constant time against CaveatAudience entries
	// in the cap. Setting Identity to the zero hash disables the
	// audience check — useful for IAM itself (which mints caps for
	// anyone) and for resource servers that haven't onboarded an
	// identity yet, but production resource servers MUST set it.
	Identity [32]byte

	// MLDSA65Ctx is the FIPS 204 §5.2 domain-separation context string
	// that ML-DSA-65 signers used at issue time. The verifier passes it
	// into mldsa65.Verify so a cap minted with ctx="hanzo-iam/cap/v1"
	// only verifies under a verifier configured with the same ctx —
	// preventing cross-protocol signature replay.
	//
	// Leaving this empty is legal (matches an empty signer ctx) but
	// cryptographically discouraged for production deployments.
	MLDSA65Ctx []byte
}

type MLDSA65Signer struct {
	// contains filtered or unexported fields
}

type MemoryRegistry struct {
	// contains filtered or unexported fields
}

type MemoryStore struct {
	// contains filtered or unexported fields
}

type ProcessConfig struct {
	// Seed is the 32-byte ed25519 seed loaded from KMS. The caller is
	// responsible for wiping this slice after InitProcessIssuer returns.
	Seed []byte

	// CtxID is the per-deployment label baked into log lines + future
	// PQ signer context. Today only carried for traceability.
	CtxID string
}

type RevocationStore interface {
	// IsRevoked reports whether capID has been revoked. Must be safe
	// for concurrent use. Implementations should return false on lookup
	// errors; a transient storage failure must not cause caps to be
	// silently accepted as valid, so callers wrap this with a tighter
	// freshness budget at a higher layer.
	IsRevoked(capID [32]byte) bool

	// Revoke marks capID as revoked. Idempotent. Must be safe for
	// concurrent use.
	Revoke(capID [32]byte)
}

type Scheme = cap.Scheme

type SystemClock struct{}

type Verifier = LibVerifier

type VerifyParams struct {
	// Leaf is the cap the wielder is presenting.
	Leaf cap.Cap

	// Chain is the chain of parent caps from Leaf.Parent up to root.
	// chain[0] is Leaf's parent; chain[len-1] is the root (Parent ==
	// zero). An empty Chain means Leaf is itself a root.
	Chain []cap.Cap

	// RequiredOp is the bitmask of operations the caller is about to
	// perform. Verify rejects if Leaf.Permissions does not cover every
	// bit set here.
	RequiredOp uint64

	// Target is the 32-byte hash of the object the caller is acting on.
	// Verify rejects if Leaf.Target does not match.
	Target [32]byte

	// Holder is the 32-byte hash of the holder presenting the cap.
	// Verify rejects if Leaf.Holder does not match. v1 has no
	// proof-of-possession; this is a sanity check that the holder field
	// names the principal the caller's higher-level auth layer believes
	// is acting.
	Holder [32]byte
}