Documentation
¶
Overview ¶
Package capabilitymemory provides process-local replay and revocation adapters. State is not shared across processes and therefore cannot provide cluster-wide one-time or instant revocation semantics. Start with explicit clocks and NewConsumptionStore/NewRevocations; finite limits cover per-store record and owned string admission, not exact heap usage. Callers own cleanup, revocation insertion errors and shutdown; no background worker or cgo is added. Store mutation/read methods serialize on their owner locks (DEC-008/009).
Index ¶
- type Clock
- type ConsumptionStore
- type Revocations
- func (store *Revocations) Check(ctx context.Context, query capability.RevocationQuery) (bool, error)
- func (store *Revocations) RevokeCapability(ctx context.Context, issuer, capabilityID string) error
- func (store *Revocations) RevokeIssuedBefore(ctx context.Context, issuer string, cutoff time.Time) error
- func (store *Revocations) RevokeKey(ctx context.Context, issuer, keyID string) error
- func (store *Revocations) RevokeResource(ctx context.Context, issuer, tenant, resource string) error
- func (store *Revocations) RevokeSubject(ctx context.Context, issuer, subject string) error
- type StoreLimits
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Clock ¶
type Clock interface {
// Now supplies trusted wall time concurrently and promptly; called outside store
// locks.
Now() time.Time
}
Clock supplies wall time for expiry decisions.
type ConsumptionStore ¶
type ConsumptionStore struct {
// contains filtered or unexported fields
}
ConsumptionStore owns finite process-local atomic replay state. Construct it with NewConsumptionStore or NewConsumptionStoreWithLimits; its zero value is not usable. Consume/Cleanup serialize on one mutex; borrowed Clock runs before acquisition and must return promptly. Records are never evicted for capacity, and no cleanup timer, close method or durable transaction is owned.
func NewConsumptionStore ¶
func NewConsumptionStore(clock Clock) (*ConsumptionStore, error)
NewConsumptionStore constructs an empty store with DefaultStoreLimits.
Example ¶
now := time.Date(2026, 9, 9, 12, 0, 0, 0, time.UTC)
store, _ := capabilitymemory.NewConsumptionStore(fixedClock{now: now})
result, err := store.Consume(context.Background(), capability.Consumption{Issuer: "ordinary-issuer",
CapabilityID: "cap-42", MaxUses: 1, ExpiresAt: now.Add(time.Minute),
})
fmt.Println(result.Use, result.Remaining, err == nil)
Output: 1 0 true
func NewConsumptionStoreWithLimits ¶
func NewConsumptionStoreWithLimits(clock Clock, limits StoreLimits) (*ConsumptionStore, error)
NewConsumptionStoreWithLimits copies explicit positive budgets. Invalid limits or a nil clock return ErrInvalidConfiguration. Clock remains trusted caller-owned code and must be safe for concurrent use.
func (*ConsumptionStore) Cleanup ¶
Cleanup removes state expiring at or before cutoff and releases its admission. The trusted caller must choose a cutoff beyond all relevant acceptance windows; removing live state can reset its allowance. No background cleanup runs.
func (*ConsumptionStore) Consume ¶
func (store *ConsumptionStore) Consume(ctx context.Context, request capability.Consumption) (capability.ConsumptionResult, error)
Consume atomically records one use. ErrCapacity refuses an oversized identity or new record before consumption without eviction or allowance reset. Repeats use no additional admission; live conflicting bounds return ErrReplayConflict and exhausted records return ErrReplayExhausted. ctx must be non-nil; expired/nonpositive/empty inputs return ErrInvalidConfiguration. Expiry is sampled before lock acquisition, without verifier skew. Cancellation is rechecked after the lock; no bounded lock wait or clock panic boundary is added.
type Revocations ¶
type Revocations struct {
// contains filtered or unexported fields
}
Revocations is a concurrency-safe finite process-local revocation set. Its five maps share one admission budget and never evict entries. Trusted administrative callers must handle ErrCapacity from every writer: a failed insertion is not a revocation. Construct it with NewRevocations or NewRevocationsWithLimits; its zero value is not usable. Writers/Check share one RWMutex; later same-process reads observe completed writes. No revocation removal, background expiry, distributed persistence or close lifecycle exists.
func NewRevocations ¶
func NewRevocations() *Revocations
NewRevocations constructs an empty set with DefaultStoreLimits.
func NewRevocationsWithLimits ¶
func NewRevocationsWithLimits(limits StoreLimits) (*Revocations, error)
NewRevocationsWithLimits copies explicit positive budgets. Invalid limits return ErrInvalidConfiguration. Duplicate writes and existing cutoff updates need no additional admission, even at capacity.
Example ¶
store, err := capabilitymemory.NewRevocationsWithLimits(capabilitymemory.StoreLimits{MaxRecords: 1, MaxStringBytes: 16})
if err != nil {
panic(err)
}
ctx := context.Background()
if err := store.RevokeCapability(ctx, "issuer", "cap-1"); err != nil {
panic(err)
}
// Capacity failure must be handled; it does not revoke the requested key.
err = store.RevokeKey(ctx, "issuer", "key-1")
fmt.Println(errors.Is(err, capability.ErrCapacity))
revoked, err := store.Check(ctx, capability.RevocationQuery{Issuer: "issuer", CapabilityID: "cap-1"})
fmt.Println(revoked, err == nil)
Output: true true true
func (*Revocations) Check ¶
func (store *Revocations) Check(ctx context.Context, query capability.RevocationQuery) (bool, error)
Check reports whether any exact revocation boundary matches query. Its aggregate input string length must fit MaxStringBytes before any map lookup; otherwise it returns false, ErrCapacity. Verify sanitizes checker failures as ErrRevocationUnknown and returns no grant. Direct query fields need not be authenticated by this method; ctx must be non-nil. It rechecks cancellation under a read lock, but does not provide a cancellable/bounded lock acquisition.
func (*Revocations) RevokeCapability ¶
func (store *Revocations) RevokeCapability(ctx context.Context, issuer, capabilityID string) error
RevokeCapability revokes one capability ID within an issuer namespace.
func (*Revocations) RevokeIssuedBefore ¶
func (store *Revocations) RevokeIssuedBefore(ctx context.Context, issuer string, cutoff time.Time) error
RevokeIssuedBefore revokes capabilities issued strictly before cutoff. A later cutoff replaces an earlier one; the boundary never moves backward.
func (*Revocations) RevokeKey ¶
func (store *Revocations) RevokeKey(ctx context.Context, issuer, keyID string) error
RevokeKey revokes every capability signed by one key ID for an issuer.
func (*Revocations) RevokeResource ¶
func (store *Revocations) RevokeResource(ctx context.Context, issuer, tenant, resource string) error
RevokeResource revokes an exact issuer, tenant, and resource boundary.
func (*Revocations) RevokeSubject ¶
func (store *Revocations) RevokeSubject(ctx context.Context, issuer, subject string) error
RevokeSubject revokes every subject-bound capability for an issuer.
type StoreLimits ¶
type StoreLimits struct {
// MaxRecords is the aggregate number of retained records, including expired
// replay records until removed. It must be positive.
MaxRecords int
// MaxStringBytes bounds the sum of each retained key's string lengths and
// each operation's input strings before hashing. It must be positive. This
// excludes map/record/allocator overhead and caller-owned backing storage.
MaxStringBytes int
}
StoreLimits bounds one store's retained records and owned string bytes. Revocations share the allowance across all five revocation boundaries.
func DefaultStoreLimits ¶
func DefaultStoreLimits() StoreLimits
DefaultStoreLimits returns finite process-local defaults: 10,000 records and 4 MiB of retained string bytes. Map and record overhead is additional.
Source Files