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.
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 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. Records are never evicted to make room for another identity.
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.
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.
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.
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