@apoa/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,506 @@
+/** The human granting authority. */
+interface Principal {
+    id: string;
+    name?: string;
+}
+/** The AI agent receiving authority. */
+interface Agent {
+    id: string;
+    name?: string;
+    provider?: string;
+}
+/** Allowed constraint value types. */
+type ConstraintValue = boolean | number | string | string[];
+/** A map of constraint names to their values. */
+type ConstraintMap = Record<string, ConstraintValue>;
+/** How the agent accesses the service. */
+type AccessMode = 'api' | 'browser';
+/** Configuration for browser-based access via secure credential injection. */
+interface BrowserSessionConfig {
+    allowedUrls: string[];
+    credentialVaultRef: string;
+    allowFormInteraction?: boolean;
+    allowNavigation?: boolean;
+    maxSessionDuration?: number;
+    captureScreenshots?: boolean;
+    blockedActions?: string[];
+}
+/** Configuration for API-based access. */
+interface APIAccessConfig {
+    authorizationServer?: string;
+    oauthScopes?: string[];
+    useDPoP?: boolean;
+}
+/** The organization operating the AI agent. */
+interface AgentProvider {
+    name: string;
+    id?: string;
+    contact?: string;
+}
+/** The legal model under which this authorization operates. */
+interface LegalFramework {
+    model: 'provider-as-agent';
+    jurisdiction?: string;
+    legalBasis?: string[];
+    pairedLegalInstrument?: boolean;
+}
+/** A service the agent is authorized to access. */
+interface ServiceAuthorization {
+    service: string;
+    scopes: string[];
+    constraints?: ConstraintMap;
+    accessMode?: AccessMode;
+    browserConfig?: BrowserSessionConfig;
+    apiConfig?: APIAccessConfig;
+}
+/** Called when a soft rule is violated. */
+type OnRuleViolation = (violation: RuleViolation) => void | Promise<void>;
+/** Rules that govern agent behavior. */
+interface Rule {
+    id: string;
+    description: string;
+    enforcement: 'hard' | 'soft';
+    onViolation?: OnRuleViolation;
+}
+/** Logged when a soft rule is violated. */
+interface RuleViolation {
+    ruleId: string;
+    tokenId: string;
+    action: string;
+    service: string;
+    timestamp: Date;
+    details?: string;
+}
+/** Metadata values are JSON-serializable primitives only. */
+type MetadataValue = string | number | boolean | null;
+/** Token metadata — flat key-value pairs. Max 20 keys, max 1KB serialized. */
+type TokenMetadata = Record<string, MetadataValue>;
+/** The full APOA authorization definition. */
+interface APOADefinition {
+    principal: Principal;
+    agent: Agent;
+    agentProvider?: AgentProvider;
+    services: ServiceAuthorization[];
+    rules?: Rule[];
+    notBefore?: Date | string;
+    expires: Date | string;
+    revocable?: boolean;
+    delegatable?: boolean;
+    maxDelegationDepth?: number;
+    metadata?: TokenMetadata;
+    legal?: LegalFramework;
+}
+/** A signed, issued APOA token. */
+interface APOAToken {
+    jti: string;
+    definition: APOADefinition;
+    issuedAt: Date;
+    signature: string;
+    issuer: string;
+    audience?: string[];
+    parentToken?: string;
+    raw: string;
+}
+/** Audit detail values — serializable primitives only. */
+type AuditDetailValue = string | number | boolean | null;
+/** What gets logged every time the agent does something. */
+interface AuditEntry {
+    tokenId: string;
+    timestamp: Date;
+    action: string;
+    service: string;
+    result: 'allowed' | 'denied' | 'escalated';
+    details?: Record<string, AuditDetailValue>;
+    url?: string;
+    screenshotRef?: string;
+    accessMode?: AccessMode;
+}
+/** Scope check result. */
+interface ScopeCheckResult {
+    allowed: boolean;
+    reason: string;
+    matchedScope?: string;
+    constraint?: string;
+}
+/** Revocation record. */
+interface RevocationRecord {
+    tokenId: string;
+    revokedAt: Date;
+    revokedBy: string;
+    reason?: string;
+    cascaded: string[];
+}
+/** Options for revoking a token. */
+interface RevocationOptions {
+    revokedBy: string;
+    reason?: string;
+    cascade?: boolean;
+}
+/** Options for querying audit trails. */
+interface AuditQueryOptions {
+    from?: Date;
+    to?: Date;
+    action?: string;
+    service?: string;
+    result?: 'allowed' | 'denied' | 'escalated';
+    limit?: number;
+    offset?: number;
+}
+/** Result of verifying a delegation chain. */
+interface ChainVerificationResult {
+    valid: boolean;
+    depth: number;
+    errors: string[];
+    failedAt?: number;
+    root: APOAToken;
+    leaf: APOAToken;
+}
+/** An ordered list of tokens from root to leaf. */
+type DelegationChain = APOAToken[];
+/** Definition for creating a delegated token. */
+interface DelegationDefinition {
+    agent: Agent;
+    services: ServiceAuthorization[];
+    rules?: Rule[];
+    expires?: Date | string;
+    metadata?: TokenMetadata;
+}
+/** Options for signing tokens. */
+interface SigningOptions {
+    privateKey: CryptoKey;
+    algorithm?: 'EdDSA' | 'ES256';
+    kid?: string;
+}
+/** Options for validating tokens. */
+interface ValidationOptions {
+    publicKey?: CryptoKey;
+    keyResolver?: KeyResolver;
+    publicKeyResolver?: (issuer: string) => Promise<CryptoKey>;
+    checkRevocation?: boolean;
+    revocationStore?: RevocationStore;
+    clockSkew?: number;
+}
+/** Result of token validation. */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    token?: APOAToken;
+    warnings?: string[];
+}
+/** Resolves a public key by its Key ID. */
+interface KeyResolver {
+    resolve(kid: string): Promise<CryptoKey | null>;
+}
+/** Options for the authorize() function. */
+interface AuthorizeOptions {
+    revocationStore?: RevocationStore;
+    auditStore?: AuditStore;
+    context?: Record<string, ConstraintValue>;
+}
+/** Result of an authorization check. */
+interface AuthorizationResult {
+    authorized: boolean;
+    reason?: string;
+    checks: {
+        revoked: boolean;
+        scopeAllowed?: boolean;
+        constraintsPassed?: boolean;
+        rulesPassed?: boolean;
+    };
+    violations?: RuleViolation[];
+}
+/** Revocation store interface. */
+interface RevocationStore {
+    add(record: RevocationRecord): Promise<void>;
+    check(tokenId: string): Promise<RevocationRecord | null>;
+    list(principalId: string): Promise<RevocationRecord[]>;
+}
+/** Audit store interface. */
+interface AuditStore {
+    append(entry: AuditEntry): Promise<void>;
+    query(tokenId: string, options?: AuditQueryOptions): Promise<AuditEntry[]>;
+    queryByService(service: string, options?: AuditQueryOptions): Promise<AuditEntry[]>;
+}
+/** Options for creating a client. */
+interface APOAClientOptions {
+    revocationStore?: RevocationStore;
+    auditStore?: AuditStore;
+    keyResolver?: KeyResolver;
+    defaultSigningOptions?: Partial<SigningOptions>;
+}
+/** The configured APOA client. */
+interface APOAClient {
+    createToken(definition: APOADefinition, options?: SigningOptions): Promise<APOAToken>;
+    parseDefinition(input: string, format?: 'yaml' | 'json'): APOADefinition;
+    validateToken(token: string | APOAToken, options?: Omit<ValidationOptions, 'revocationStore'>): Promise<ValidationResult>;
+    generateKeyPair(algorithm?: 'EdDSA' | 'ES256'): Promise<CryptoKeyPair>;
+    checkScope(token: APOAToken, service: string, action: string): ScopeCheckResult;
+    checkConstraint(token: APOAToken, service: string, constraint: string): ScopeCheckResult;
+    authorize(token: APOAToken, service: string, action: string, options?: Omit<AuthorizeOptions, 'revocationStore' | 'auditStore'>): Promise<AuthorizationResult>;
+    delegate(parentToken: APOAToken, childDef: DelegationDefinition, options?: SigningOptions): Promise<APOAToken>;
+    verifyChain(chain: DelegationChain): Promise<ChainVerificationResult>;
+    revoke(tokenId: string, options: RevocationOptions): Promise<RevocationRecord>;
+    isRevoked(tokenId: string): Promise<boolean>;
+    logAction(tokenId: string, entry: Omit<AuditEntry, 'tokenId' | 'timestamp'>): Promise<void>;
+    getAuditTrail(tokenId: string, options?: AuditQueryOptions): Promise<AuditEntry[]>;
+    getAuditTrailByService(service: string, options?: AuditQueryOptions): Promise<AuditEntry[]>;
+}
+
+/** Base error class for all APOA errors. */
+declare class APOAError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/** Thrown when a token has expired. */
+declare class TokenExpiredError extends APOAError {
+    expiredAt: Date;
+    constructor(message: string, expiredAt: Date);
+}
+/** Thrown when an action is outside the token's authorized scopes. */
+declare class ScopeViolationError extends APOAError {
+    requestedScope: string;
+    availableScopes: string[];
+    constructor(message: string, requestedScope: string, availableScopes: string[]);
+}
+/** Thrown when a delegated token tries to exceed parent permissions. */
+declare class AttenuationViolationError extends APOAError {
+    parentScope: string[];
+    requestedScope: string[];
+    constructor(message: string, parentScope: string[], requestedScope: string[]);
+}
+/** Thrown when trying to use a revoked token. */
+declare class RevocationError extends APOAError {
+    revokedAt: Date;
+    revokedBy: string;
+    constructor(message: string, revokedAt: Date, revokedBy: string);
+}
+/** Thrown when delegation chain verification fails. */
+declare class ChainVerificationError extends APOAError {
+    failedAt: number;
+    reason: string;
+    constructor(message: string, failedAt: number, reason: string);
+}
+/** Thrown when token metadata fails validation. */
+declare class MetadataValidationError extends APOAError {
+    field?: string;
+    constructor(message: string, field?: string);
+}
+/** Thrown when a hard rule is violated. */
+declare class RuleEnforcementError extends APOAError {
+    ruleId: string;
+    enforcement: 'hard';
+    constructor(message: string, ruleId: string);
+}
+/** Thrown when a definition fails validation. */
+declare class DefinitionValidationError extends APOAError {
+    errors: string[];
+    constructor(message: string, errors: string[]);
+}
+
+/**
+ * Generate an Ed25519 or ES256 key pair for signing and verifying tokens.
+ */
+declare function generateKeyPair(algorithm?: 'EdDSA' | 'ES256'): Promise<CryptoKeyPair>;
+/**
+ * Sign a payload, producing a compact JWS string.
+ */
+declare function sign(payload: Record<string, unknown>, options: SigningOptions): Promise<string>;
+/**
+ * Verify a compact JWS string and return the decoded payload.
+ */
+declare function verify(token: string, key: CryptoKey): Promise<Record<string, unknown>>;
+
+/**
+ * Check if a token/date has expired, accounting for clock skew.
+ * Returns true if the current time is past the expiration (plus tolerance).
+ */
+declare function isExpired(expires: Date | string, clockSkew?: number, now?: Date): boolean;
+/**
+ * Check if the current time is before the notBefore date, accounting for clock skew.
+ * Returns true if it's too early to use this token.
+ */
+declare function isBeforeNotBefore(notBefore: Date | string, clockSkew?: number, now?: Date): boolean;
+
+/**
+ * Parse a scope string into its segments.
+ * e.g., "appointments:read" → ["appointments", "read"]
+ */
+declare function parseScope(scope: string): string[];
+/**
+ * Check if a scope pattern matches a requested scope.
+ *
+ * Rules:
+ * 1. Root wildcard "*" matches everything
+ * 2. Exact match: "appointments:read" matches "appointments:read"
+ * 3. Wildcard at level: "appointments:*" matches "appointments:read"
+ *    but NOT "appointments:read:summary" (wildcards don't cross levels)
+ * 4. Segment-by-segment matching with wildcard support at each level
+ */
+declare function matchScope(pattern: string, requested: string): boolean;
+
+/**
+ * In-memory revocation store for dev/testing.
+ * Data is lost when the process exits.
+ */
+declare class MemoryRevocationStore implements RevocationStore {
+    private records;
+    add(record: RevocationRecord): Promise<void>;
+    check(tokenId: string): Promise<RevocationRecord | null>;
+    list(principalId: string): Promise<RevocationRecord[]>;
+}
+
+/**
+ * In-memory audit store for dev/testing.
+ * Data is lost when the process exits.
+ */
+declare class MemoryAuditStore implements AuditStore {
+    private entries;
+    append(entry: AuditEntry): Promise<void>;
+    query(tokenId: string, options?: AuditQueryOptions): Promise<AuditEntry[]>;
+    queryByService(service: string, options?: AuditQueryOptions): Promise<AuditEntry[]>;
+}
+
+/**
+ * Check if an action is allowed under a token's scopes for a given service.
+ * Synchronous — no rules, no revocation, just scope matching.
+ */
+declare function checkScope(token: APOAToken, service: string, action: string): ScopeCheckResult;
+/**
+ * Check a specific constraint on a service.
+ * Returns allowed: false if the constraint is explicitly set to false.
+ * Returns allowed: true if the constraint is not set or is truthy.
+ */
+declare function checkConstraint(token: APOAToken, service: string, constraint: string): ScopeCheckResult;
+/**
+ * One-stop authorization check: revocation + scope + constraints + rules.
+ *
+ * Enforcement order:
+ * 1. Check revocation (is the token still alive?)
+ * 2. Check scope (is the action in the authorized scope set?)
+ * 3. Check constraints (only the action's top-level segment is checked
+ *    against constraint keys — e.g. action "signing:submit" checks
+ *    constraint "signing". Use checkConstraint() for explicit checks.)
+ * 4. Check hard rules (hard rules whose id appears as a prefix of the
+ *    action → deny. e.g. rule "no-messaging" blocks "messaging:send")
+ * 5. Check soft rules (all soft rules → log violation + continue)
+ */
+declare function authorize(token: APOAToken, service: string, action: string, options?: AuthorizeOptions): Promise<AuthorizationResult>;
+
+/**
+ * Parse a YAML or JSON definition string into an APOADefinition.
+ * Auto-detects format: starts with '{' = JSON, otherwise YAML.
+ * Validates required fields, metadata constraints, browser mode config,
+ * and legal framework fields. Throws DefinitionValidationError with all
+ * problems found.
+ */
+declare function parseDefinition(input: string, format?: 'yaml' | 'json'): APOADefinition;
+
+/**
+ * Revoke a token. No cascade logic — that's Phase 3.
+ */
+declare function revoke(tokenId: string, options: RevocationOptions, store?: RevocationStore): Promise<RevocationRecord>;
+/**
+ * Check if a token has been revoked.
+ */
+declare function isRevoked(tokenId: string, store?: RevocationStore): Promise<boolean>;
+
+/**
+ * Log an action against a token.
+ */
+declare function logAction(tokenId: string, entry: Omit<AuditEntry, 'tokenId' | 'timestamp'>, store?: AuditStore): Promise<void>;
+
+/**
+ * Get the audit trail for a token.
+ */
+declare function getAuditTrail(tokenId: string, options?: AuditQueryOptions, store?: AuditStore): Promise<AuditEntry[]>;
+/**
+ * Get the audit trail for a service — across all tokens.
+ */
+declare function getAuditTrailByService(service: string, options?: AuditQueryOptions, store?: AuditStore): Promise<AuditEntry[]>;
+
+/**
+ * Create an APOA token from a definition.
+ * Generates a UUID for jti, validates metadata, derives audience,
+ * warns at 4KB, rejects above 8KB.
+ */
+declare function createToken(definition: APOADefinition, options: SigningOptions): Promise<APOAToken>;
+
+/**
+ * Sign an APOA token payload as a compact JWS.
+ * Embeds `kid` in the JWT header when provided.
+ * Supports EdDSA (default) and ES256.
+ */
+declare function signToken(payload: Record<string, unknown>, options: SigningOptions): Promise<string>;
+/**
+ * Decode a compact JWS protected header without verifying the signature.
+ * Used to extract `kid` and `alg` for key resolution.
+ */
+declare function decodeHeader(token: string): Record<string, unknown>;
+/**
+ * Verify a compact JWS and return the decoded payload.
+ */
+declare function verifySignature(token: string, key: CryptoKey): Promise<Record<string, unknown>>;
+
+/**
+ * Validate a token — check signature, expiration, structure, revocation.
+ * Returns a detailed result with all errors found.
+ *
+ * Accepts either a raw JWT string or an APOAToken object.
+ * When given a string, decodes and verifies the signature.
+ * When given an APOAToken, uses the .raw field for signature verification.
+ */
+declare function validateToken(token: string | APOAToken, options: ValidationOptions): Promise<ValidationResult>;
+
+/**
+ * Cascade revoke: revoke a parent token and all child tokens in a delegation chain.
+ * Populates RevocationRecord.cascaded with child token IDs.
+ *
+ * @param parentTokenId - The parent token's jti to revoke
+ * @param childTokenIds - Array of child token jti values to cascade-revoke
+ * @param options - Revocation options (revokedBy, reason)
+ * @param store - Optional revocation store
+ */
+declare function cascadeRevoke(parentTokenId: string, childTokenIds: string[], options: RevocationOptions, store?: RevocationStore): Promise<RevocationRecord>;
+
+/**
+ * Verify that a delegation definition is a valid attenuation of a parent token.
+ * Throws AttenuationViolationError on any violation.
+ *
+ * Checks:
+ * 1. Child scopes are a subset of parent scopes (per service)
+ * 2. Child constraints do not relax parent constraints
+ * 3. Child expiration <= parent expiration
+ * 4. maxDelegationDepth is not exceeded
+ * 5. Child does not add services the parent doesn't have
+ * 6. Child rules only add, never remove parent rules
+ */
+declare function verifyAttenuation(parent: APOAToken, child: DelegationDefinition, currentDepth?: number): void;
+
+/**
+ * Create a delegated (attenuated) token from a parent token.
+ *
+ * - Inherits principal from parent (cannot be overridden)
+ * - Sets parentToken on child to parent's jti
+ * - Enforces attenuation rules
+ * - Additional rules can only be added, not removed
+ */
+declare function delegate(parentToken: APOAToken, childDef: DelegationDefinition, options: SigningOptions): Promise<APOAToken>;
+
+/**
+ * Verify a full delegation chain.
+ *
+ * - Verifies every link attenuates the previous one (scopes are subsets)
+ * - Checks expiration of every token (if any parent expired, chain is invalid)
+ * - If RevocationStore provided, checks revocation of every token
+ * - Reports all errors found, plus failedAt index
+ */
+declare function verifyChain(chain: DelegationChain, store?: RevocationStore): Promise<ChainVerificationResult>;
+
+/**
+ * Create a configured APOA client.
+ * Wires up RevocationStore and AuditStore so methods don't need explicit store params.
+ * Defaults to MemoryRevocationStore + MemoryAuditStore for zero-config dev/testing.
+ */
+declare function createClient(options?: APOAClientOptions): APOAClient;
+
+export { type APIAccessConfig, type APOAClient, type APOAClientOptions, type APOADefinition, APOAError, type APOAToken, type AccessMode, type Agent, type AgentProvider, AttenuationViolationError, type AuditDetailValue, type AuditEntry, type AuditQueryOptions, type AuditStore, type AuthorizationResult, type AuthorizeOptions, type BrowserSessionConfig, ChainVerificationError, type ChainVerificationResult, type ConstraintMap, type ConstraintValue, DefinitionValidationError, type DelegationChain, type DelegationDefinition, type KeyResolver, type LegalFramework, MemoryAuditStore, MemoryRevocationStore, MetadataValidationError, type MetadataValue, type OnRuleViolation, type Principal, RevocationError, type RevocationOptions, type RevocationRecord, type RevocationStore, type Rule, RuleEnforcementError, type RuleViolation, type ScopeCheckResult, ScopeViolationError, type ServiceAuthorization, type SigningOptions, TokenExpiredError, type TokenMetadata, type ValidationOptions, type ValidationResult, authorize, cascadeRevoke, checkConstraint, checkScope, createClient, createToken, decodeHeader, delegate, generateKeyPair, getAuditTrail, getAuditTrailByService, isBeforeNotBefore, isExpired, isRevoked, logAction, matchScope, parseDefinition, parseScope, revoke, sign, signToken, validateToken, verify, verifyAttenuation, verifyChain, verifySignature };