capability

type Algorithm string

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

type BoundedResolverOptions struct {
	// Source is mandatory borrowed policy; it must honor context and return promptly.
	Source Resolver
	// Timeout must be positive and bounds a cooperative source, not arbitrary callback
	// execution.
	Timeout time.Duration
	// AllowedAlgorithms must be nonempty/unique built-in constructions and is copied into
	// an allowlist.
	AllowedAlgorithms []Algorithm
	// MaxKeyIDBytes must be positive and at most 256, checked before a source call.
	MaxKeyIDBytes int
}

type Consumption struct {
	// Issuer is required authenticated namespace; never merge equal IDs across issuers.
	Issuer string
	// CapabilityID is required exact signed identity, not an application transaction ID.
	CapabilityID string
	// ExpiresAt is signed expiry bound; each store applies its own clock and supported
	// precision.
	ExpiresAt time.Time
	// MaxUses must be positive for direct store calls and remains immutable for live
	// identity.
	MaxUses uint32
}

type ConsumptionResult struct {
	// Use is the one-based committed ordinal for bounded uses; zero for reusable grants.
	Use uint32
	// Remaining is the allowance after this committed use, not a reservation for future
	// operations.
	Remaining uint32
	// Reusable is true only for the core unbounded-use shortcut; Use/Remaining are then
	// zero.
	Reusable bool
}

type ConsumptionStore interface {
	// Consume atomically compares exact issuer/ID, live expiry/max and count before
	// increment. Honor ctx; document server clock/precision, retention and unknown
	// commit windows.
	Consume(context.Context, Consumption) (ConsumptionResult, error)
}

type ConsumptionStoreFunc func(context.Context, Consumption) (ConsumptionResult, error)

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

type Header struct {
	// Version must be 1 for local cap1 framing.
	Version int `json:"v"`
	// Type must be capability, not a JWT/JWS media type.
	Type string `json:"typ"`
	// Algorithm is protected but cannot select a different trusted verifier construction.
	Algorithm Algorithm `json:"alg"`
	// KeyID is protected public key identity with a fixed 256-byte canonical-header
	// ceiling.
	KeyID string `json:"kid"`
}

type Key struct {
	// Issuer is required independently established key ownership, never inferred from a
	// token.
	Issuer string
	// ID is required globally unique exact key identity with a 256-byte ceiling.
	ID string
	// Verifier is mandatory borrowed trusted code; concurrent resolution/use requires it to
	// be safe.
	Verifier Verifier
	// Disabled refuses verified use without marking compromise.
	Disabled bool
	// Revoked refuses verified use regardless of Disabled.
	Revoked bool
	// NotBefore is inclusive unskewed activation; zero is open.
	NotBefore time.Time
	// NotAfter is exclusive unskewed expiry; zero is open, otherwise must follow nonzero
	// NotBefore.
	NotAfter time.Time
}

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

type Limits struct {
	// MaxTokenBytes caps encoded payload input/output and complete token bytes; positive,
	// not an exact heap quota.
	MaxTokenBytes int
	// MaxFieldBytes caps bounded text fields; positive. Protected key IDs retain a separate
	// 256-byte ceiling.
	MaxFieldBytes int
	// MaxAudiences is the positive maximum audience count.
	MaxAudiences int
	// MaxCaveats is the maximum caveat count; zero permits none, negative is invalid.
	MaxCaveats int
	// MaxCaveatBytes is the positive byte limit for each caveat value.
	MaxCaveatBytes int
	// MaxLifetime is positive; expiry minus the earlier issued/not-before second must fit
	// its whole seconds.
	MaxLifetime time.Duration
	// MaxUses is the positive ceiling on signed bounded use counts; payload zero still
	// means reusable.
	MaxUses uint32
}

type Parsed struct {
	// Header is decoded untrusted metadata, not trusted resolver policy.
	Header Header
	// Payload is decoded untrusted authority with caller-owned slices/maps; changing it
	// does not verify anything.
	Payload Payload
	// contains filtered or unexported fields
}

type Payload struct {
	// Version must be local wire version 1, independent of the Go module major.
	Version int
	// Issuer is required exact issuer text; verification separately binds trusted key
	// ownership.
	Issuer string
	// Audiences is required borrowed text; canonicalization copies/sorts it and rejects
	// duplicate values.
	Audiences []string
	// Subject is the exact independently authenticated subject; it is mutually exclusive
	// with Bearer.
	Subject string
	// Bearer permits use without subject matching and requires an empty Subject; tokens
	// remain transferable.
	Bearer bool
	// Resource is required exact application authority; SignURL owns it instead.
	Resource string
	// Operation is required exact application operation; SignURL substitutes its HTTP
	// method.
	Operation string
	// IssuedAt encodes nonnegative Unix seconds; subsecond precision is discarded.
	IssuedAt time.Time
	// NotBefore encodes nonnegative Unix seconds; it may precede IssuedAt, but expiry must
	// follow both.
	NotBefore time.Time
	// ExpiresAt is exclusive signed Unix-second expiry; Verify applies caller skew
	// separately.
	ExpiresAt time.Time
	// ID is required public capability identity; callers generate collision-resistant
	// values per issuer.
	ID string
	// Tenant is exact optional authority; empty is an explicit empty boundary.
	Tenant string
	// CorrelationID is optional diagnostic attribution, never authorization.
	CorrelationID string
	// MaxUses zero is reusable; positive requires explicit atomic consumption, not just
	// verification.
	MaxUses uint32
	// Caveats is an optional borrowed map of exact required pairs; Use may supply extras.
	Caveats map[string]string
}

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

type Purpose string

type Reference struct {
	// CapabilityID is the original bounded grant ID, not proof of existence.
	CapabilityID string
	// Purpose is the exact literal operation bound by the producer.
	Purpose Purpose
	// Digest identifies original canonical token framing, not use authority.
	Digest [32]byte
	// ExpiresAt is the exclusive original expiry at UTC whole-second precision.
	ExpiresAt time.Time
}

type ResolvedKey struct {
	// Issuer is the trusted namespace owning this key, not a token-derived claim.
	Issuer string
	// Verifier is mandatory borrowed trusted cryptographic code; typed nil is not detected.
	Verifier Verifier
	// Disabled refuses use without declaring the key revoked.
	Disabled bool
	// Revoked refuses all use and takes precedence over Disabled.
	Revoked bool
	// NotBefore is inclusive key activation at unskewed verification time; zero is open.
	NotBefore time.Time
	// NotAfter is exclusive key expiry at unskewed verification time; zero is open.
	NotAfter time.Time
}

type Resolver interface {
	// Resolve supplies independently trusted issuer/key policy for exact global
	// ID/algorithm; honor ctx and return safe ErrUnknownKey/ErrAlgorithmMismatch
	// categories.
	Resolve(context.Context, string, Algorithm) (ResolvedKey, error)
}

type ResolverFunc func(context.Context, string, Algorithm) (ResolvedKey, error)

type RevocationChecker interface {
	// Check returns true for revoked authority, false only after successful policy
	// read. Errors fail Verify closed as ErrRevocationUnknown; document
	// propagation/cache staleness.
	Check(context.Context, RevocationQuery) (bool, error)
}

type RevocationCheckerFunc func(context.Context, RevocationQuery) (bool, error)

type RevocationQuery struct {
	// Issuer is authenticated exact namespace for every matching boundary.
	Issuer string
	// Tenant scopes resource revocation; empty remains exact.
	Tenant string
	// CapabilityID is authenticated signed ID for individual revocation.
	CapabilityID string
	// KeyID is authenticated protected key identity for issuer/key revocation.
	KeyID string
	// Subject is authenticated subject; memory skips this boundary when empty.
	Subject string
	// Resource is authenticated exact application authority, not a filesystem or egress
	// permission.
	Resource string
	// IssuedAt is signed issue time; memory issued-before cutoffs match strictly earlier
	// times.
	IssuedAt time.Time
}

type Service interface {
	// Issue signs one payload under the selected issuer and returns owned proof
	// custody plus reference metadata. Expiry must be explicit; no use is consumed.
	Issue(context.Context, Payload) (Proof, Reference, error)
	// Verify authenticates a private proof snapshot and exact purpose/audience.
	// It returns zero on failure and never consumes or transfers the proof.
	Verify(context.Context, Proof, Purpose, string) (Grant, error)
}

type ServiceConfig struct {
	// Issuer is independently selected trusted deployment policy, not a token
	// claim. It fixes both issuance and verification to this exact key owner.
	Issuer string
	// Signer is the borrowed mandatory issuer-owned signing collaborator.
	Signer Signer
	// Resolver supplies independently trusted key ownership and lifecycle policy.
	Resolver Resolver
	// Clock is a borrowed fast local trusted clock, invoked outside custody locks.
	Clock func() time.Time
	// Limits bounds parsing and issuance; zero selects no implicit defaults.
	Limits Limits
	// Skew is nonnegative payload time tolerance, never key-lifecycle tolerance.
	Skew time.Duration
	// Revocations optionally checks current policy after signature/time validation.
	// Nil is permitted only when deployment policy allows no revocation source.
	Revocations RevocationChecker
}

type Signer interface {
	// Algorithm returns the stable trusted construction, never untrusted caller
	// selection.
	Algorithm() Algorithm
	// KeyID returns stable public identity as valid nonempty text <=256 bytes.
	KeyID() string
	// Sign authenticates exact borrowed bytes, honoring context and returning owned
	// signature storage.
	Sign(context.Context, []byte) ([]byte, error)
}

type URLProfile struct {
	// Name is required versioned local policy identity stored in a reserved caveat.
	Name string
	// SignatureParameter is required token query name and must not also be allowlisted.
	SignatureParameter string
	// AllowRelative permits path/query-only authority; the application must supply trusted
	// origin context.
	AllowRelative bool
	// AllowedSchemes is borrowed sorted/unique http/https names; empty is allowed only for
	// relative-only policy.
	AllowedSchemes []string
	// AllowedAuthorities is borrowed sorted/unique canonical lowercase ASCII authorities
	// paired with schemes.
	AllowedAuthorities []string
	// QueryParameters is borrowed sorted/unique allowed query names, excluding
	// SignatureParameter.
	QueryParameters []string
	// RequireBodyDigest requires exactly 32 caller-supplied SHA-256 bytes covered through a
	// reserved caveat.
	RequireBodyDigest bool
}

type URLRequest struct {
	// Method is an exact nonempty uppercase HTTP token, not normalized.
	Method string
	// RawURL is borrowed URL text; verification requires canonical presentation, signing
	// normalizes it.
	RawURL string
	// BodyDigest is borrowed precomputed SHA-256 data; omit it when the profile does not
	// require a digest.
	BodyDigest []byte
}

type Use struct {
	// Issuer must match the application-selected nonempty issuer exactly.
	Issuer string
	// Audience must equal one authenticated audience.
	Audience string
	// Subject must match subject-bound grants; bearer grants do not check it.
	Subject string
	// Resource must equal authenticated resource bytes exactly.
	Resource string
	// Operation must equal authenticated operation bytes exactly.
	Operation string
	// Tenant must equal authenticated tenant, including empty.
	Tenant string
	// Caveats is borrowed attempted-use data; every encoded caveat must match, extras are
	// ignored.
	Caveats map[string]string
}

type Verifier interface {
	// Algorithm returns the stable trusted construction, never untrusted caller
	// selection.
	Algorithm() Algorithm
	// Verify returns nil only for authentic exact borrowed bytes; honor ctx, retain
	// no inputs and return ErrInvalidSignature on refusal.
	Verify(context.Context, []byte, []byte) error
}

type VerifyOptions struct {
	// Issuer is selected by trusted application configuration. It is required
	// and must match both the signed claim and the resolved key's owner.
	Issuer string
	// Now is required trusted processing time; no clock is implicitly sampled.
	Now time.Time
	// Skew is nonnegative tolerance on payload validity, not key activation or store
	// expiry.
	Skew time.Duration
	// Limits is explicit finite parser policy; zero is invalid.
	Limits Limits
	// Revocations is optional borrowed policy invoked after signature/time validation; nil
	// disables that check.
	Revocations RevocationChecker
}