@apoa/core 0.1.2 → 0.2.1

package/dist/index.d.cts

@@ -179,6 +179,13 @@ interface ValidationOptions {
     checkRevocation?: boolean;
     revocationStore?: RevocationStore;
     clockSkew?: number;
+    /**
+     * Permitted JWS algorithms. The token's `alg` header must appear in this
+     * list or validation fails. Defaults to `['EdDSA', 'ES256']` (the APOA
+     * conformance baseline). Pin to a single value to enforce an org policy
+     * (e.g. EdDSA-only).
+     */
+    algorithms?: ('EdDSA' | 'ES256')[];
 }
 /** Result of token validation. */
 interface ValidationResult {
@@ -330,11 +337,14 @@ 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"
+ * 1. Empty pattern or empty requested string never matches (a vacuous match
+ *    on `''` would let a token with `scopes: ['']` authorize an empty
+ *    action, or vice versa).
+ * 2. Root wildcard "*" matches everything (non-empty)
+ * 3. Exact match: "appointments:read" matches "appointments:read"
+ * 4. 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
+ * 5. Segment-by-segment matching with wildcard support at each level
  */
 declare function matchScope(pattern: string, requested: string): boolean;
 
@@ -396,13 +406,18 @@ declare function authorize(token: APOAToken, service: string, action: string, op
 declare function parseDefinition(input: string, format?: 'yaml' | 'json'): APOADefinition;
 
 /**
- * Revoke a token. No cascade logic — that's Phase 3.
+ * Revoke a token. The caller MUST supply a RevocationStore so the revocation
+ * is durable and visible to other parts of the system. There is no default
+ * store: a process-shared singleton would silently diverge from the store
+ * used by `createClient()` and any caller-supplied store, producing
+ * "succeeded but never enforced" revocations.
  */
-declare function revoke(tokenId: string, options: RevocationOptions, store?: RevocationStore): Promise<RevocationRecord>;
+declare function revoke(tokenId: string, options: RevocationOptions, store: RevocationStore): Promise<RevocationRecord>;
 /**
- * Check if a token has been revoked.
+ * Check if a token has been revoked. Caller must supply the same
+ * RevocationStore that revoke() wrote to.
  */
-declare function isRevoked(tokenId: string, store?: RevocationStore): Promise<boolean>;
+declare function isRevoked(tokenId: string, store: RevocationStore): Promise<boolean>;
 
 /**
  * Log an action against a token.
@@ -423,7 +438,7 @@ declare function getAuditTrailByService(service: string, options?: AuditQueryOpt
  * Generates a UUID for jti, validates metadata, derives audience,
  * warns at 4KB, rejects above 8KB.
  */
-declare function createToken(definition: APOADefinition, options: SigningOptions): Promise<APOAToken>;
+declare function createToken(definition: APOADefinition, options: SigningOptions, parentTokenId?: string): Promise<APOAToken>;
 
 /**
  * Sign an APOA token payload as a compact JWS.
@@ -452,15 +467,19 @@ declare function verifySignature(token: string, key: CryptoKey): Promise<Record<
 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.
+ * Cascade revoke: revoke a parent token and all child tokens in a delegation
+ * chain. Populates RevocationRecord.cascaded with child token IDs.
+ *
+ * The caller MUST supply a RevocationStore. There is no default store: a
+ * process-shared singleton would silently diverge from the store used by
+ * `createClient()` and any caller-supplied store.
  *
  * @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
+ * @param store - The revocation store to write to
  */
-declare function cascadeRevoke(parentTokenId: string, childTokenIds: string[], options: RevocationOptions, store?: RevocationStore): Promise<RevocationRecord>;
+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.
@@ -493,9 +512,83 @@ declare function delegate(parentToken: APOAToken, childDef: DelegationDefinition
  * - 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
+ *
+ * IMPORTANT: This function checks structural integrity (attenuation, expiry,
+ * revocation, parentToken links) but does NOT verify cryptographic signatures.
+ * Each token in the chain MUST be validated via validateToken() before passing
+ * to verifyChain(). Passing unvalidated APOAToken objects defeats chain security.
  */
 declare function verifyChain(chain: DelegationChain, store?: RevocationStore): Promise<ChainVerificationResult>;
 
+type DefinitionLike = {
+    parentToken?: unknown;
+    delegationChain?: unknown;
+};
+type TokenLike = {
+    parentToken?: unknown;
+    definition?: DefinitionLike;
+};
+/**
+ * Return ancestor token IDs referenced by a token-like object.
+ *
+ * Canonical SDK tokens use `parentToken` for the direct parent. Some transport
+ * adapters also carry `definition.delegationChain` snapshots or message
+ * metadata with ancestor IDs. This helper normalizes those forms so revocation
+ * checks can consistently include every known ancestor.
+ */
+declare function getDelegationAncestorIds(input: APOAToken | TokenLike | DefinitionLike): string[];
+
+/** A JSON Web Key as defined by RFC 7517. */
+interface JWK {
+    kty: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    kid: string;
+    use?: 'sig' | 'enc';
+    alg?: string;
+    [key: string]: unknown;
+}
+/** A JSON Web Key Set as defined by RFC 7517 §5. */
+interface JWKS {
+    keys: JWK[];
+}
+interface PublicKeyToJWKOptions {
+    kid: string;
+    use?: 'sig' | 'enc';
+    alg?: 'EdDSA' | 'ES256';
+}
+/**
+ * Convert a public CryptoKey into a JWK. The `kid` is required so callers
+ * can match keys against the `kid` header on signed tokens. `alg` defaults
+ * to the algorithm implied by the key type (`EdDSA` for Ed25519, `ES256`
+ * for P-256).
+ */
+declare function publicKeyToJWK(publicKey: CryptoKey, options: PublicKeyToJWKOptions): Promise<JWK>;
+/** Wrap an array of JWKs in the JWKS envelope. */
+declare function buildJWKS(keys: JWK[]): JWKS;
+interface JWKSResolverOptions {
+    /** How long a fetched JWKS is cached in memory before refetch. Default 1 hour. */
+    cacheMaxAgeMs?: number;
+    /** How long a fetched JWKS is reused if a refetch fails. Default 24 hours. */
+    cooldownMs?: number;
+    /** Custom fetch implementation; defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * Allow non-https:// JWKS URLs. Off by default because APOA mandates TLS
+     * for all communication (SPEC §13.2). Use only for local development.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Create a KeyResolver backed by a remote JWKS endpoint. The resolver fetches
+ * `url`, caches the response, and returns the matching public key for a
+ * given `kid` claim. Used in conjunction with `validateToken`'s `keyResolver`
+ * option so a relying party can verify tokens signed by keys it discovers
+ * at runtime.
+ */
+declare function createJWKSResolver(url: string, options?: JWKSResolverOptions): KeyResolver;
+
 /**
  * Create a configured APOA client.
  * Wires up RevocationStore and AuditStore so methods don't need explicit store params.
@@ -503,4 +596,4 @@ declare function verifyChain(chain: DelegationChain, store?: RevocationStore): P
  */
 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 };
+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 JWK, type JWKS, type JWKSResolverOptions, type KeyResolver, type LegalFramework, MemoryAuditStore, MemoryRevocationStore, MetadataValidationError, type MetadataValue, type OnRuleViolation, type Principal, type PublicKeyToJWKOptions, 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, buildJWKS, cascadeRevoke, checkConstraint, checkScope, createClient, createJWKSResolver, createToken, decodeHeader, delegate, generateKeyPair, getAuditTrail, getAuditTrailByService, getDelegationAncestorIds, isBeforeNotBefore, isExpired, isRevoked, logAction, matchScope, parseDefinition, parseScope, publicKeyToJWK, revoke, sign, signToken, validateToken, verify, verifyAttenuation, verifyChain, verifySignature };

package/dist/index.d.ts

@@ -179,6 +179,13 @@ interface ValidationOptions {
     checkRevocation?: boolean;
     revocationStore?: RevocationStore;
     clockSkew?: number;
+    /**
+     * Permitted JWS algorithms. The token's `alg` header must appear in this
+     * list or validation fails. Defaults to `['EdDSA', 'ES256']` (the APOA
+     * conformance baseline). Pin to a single value to enforce an org policy
+     * (e.g. EdDSA-only).
+     */
+    algorithms?: ('EdDSA' | 'ES256')[];
 }
 /** Result of token validation. */
 interface ValidationResult {
@@ -330,11 +337,14 @@ 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"
+ * 1. Empty pattern or empty requested string never matches (a vacuous match
+ *    on `''` would let a token with `scopes: ['']` authorize an empty
+ *    action, or vice versa).
+ * 2. Root wildcard "*" matches everything (non-empty)
+ * 3. Exact match: "appointments:read" matches "appointments:read"
+ * 4. 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
+ * 5. Segment-by-segment matching with wildcard support at each level
  */
 declare function matchScope(pattern: string, requested: string): boolean;
 
@@ -396,13 +406,18 @@ declare function authorize(token: APOAToken, service: string, action: string, op
 declare function parseDefinition(input: string, format?: 'yaml' | 'json'): APOADefinition;
 
 /**
- * Revoke a token. No cascade logic — that's Phase 3.
+ * Revoke a token. The caller MUST supply a RevocationStore so the revocation
+ * is durable and visible to other parts of the system. There is no default
+ * store: a process-shared singleton would silently diverge from the store
+ * used by `createClient()` and any caller-supplied store, producing
+ * "succeeded but never enforced" revocations.
  */
-declare function revoke(tokenId: string, options: RevocationOptions, store?: RevocationStore): Promise<RevocationRecord>;
+declare function revoke(tokenId: string, options: RevocationOptions, store: RevocationStore): Promise<RevocationRecord>;
 /**
- * Check if a token has been revoked.
+ * Check if a token has been revoked. Caller must supply the same
+ * RevocationStore that revoke() wrote to.
  */
-declare function isRevoked(tokenId: string, store?: RevocationStore): Promise<boolean>;
+declare function isRevoked(tokenId: string, store: RevocationStore): Promise<boolean>;
 
 /**
  * Log an action against a token.
@@ -423,7 +438,7 @@ declare function getAuditTrailByService(service: string, options?: AuditQueryOpt
  * Generates a UUID for jti, validates metadata, derives audience,
  * warns at 4KB, rejects above 8KB.
  */
-declare function createToken(definition: APOADefinition, options: SigningOptions): Promise<APOAToken>;
+declare function createToken(definition: APOADefinition, options: SigningOptions, parentTokenId?: string): Promise<APOAToken>;
 
 /**
  * Sign an APOA token payload as a compact JWS.
@@ -452,15 +467,19 @@ declare function verifySignature(token: string, key: CryptoKey): Promise<Record<
 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.
+ * Cascade revoke: revoke a parent token and all child tokens in a delegation
+ * chain. Populates RevocationRecord.cascaded with child token IDs.
+ *
+ * The caller MUST supply a RevocationStore. There is no default store: a
+ * process-shared singleton would silently diverge from the store used by
+ * `createClient()` and any caller-supplied store.
  *
  * @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
+ * @param store - The revocation store to write to
  */
-declare function cascadeRevoke(parentTokenId: string, childTokenIds: string[], options: RevocationOptions, store?: RevocationStore): Promise<RevocationRecord>;
+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.
@@ -493,9 +512,83 @@ declare function delegate(parentToken: APOAToken, childDef: DelegationDefinition
  * - 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
+ *
+ * IMPORTANT: This function checks structural integrity (attenuation, expiry,
+ * revocation, parentToken links) but does NOT verify cryptographic signatures.
+ * Each token in the chain MUST be validated via validateToken() before passing
+ * to verifyChain(). Passing unvalidated APOAToken objects defeats chain security.
  */
 declare function verifyChain(chain: DelegationChain, store?: RevocationStore): Promise<ChainVerificationResult>;
 
+type DefinitionLike = {
+    parentToken?: unknown;
+    delegationChain?: unknown;
+};
+type TokenLike = {
+    parentToken?: unknown;
+    definition?: DefinitionLike;
+};
+/**
+ * Return ancestor token IDs referenced by a token-like object.
+ *
+ * Canonical SDK tokens use `parentToken` for the direct parent. Some transport
+ * adapters also carry `definition.delegationChain` snapshots or message
+ * metadata with ancestor IDs. This helper normalizes those forms so revocation
+ * checks can consistently include every known ancestor.
+ */
+declare function getDelegationAncestorIds(input: APOAToken | TokenLike | DefinitionLike): string[];
+
+/** A JSON Web Key as defined by RFC 7517. */
+interface JWK {
+    kty: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    kid: string;
+    use?: 'sig' | 'enc';
+    alg?: string;
+    [key: string]: unknown;
+}
+/** A JSON Web Key Set as defined by RFC 7517 §5. */
+interface JWKS {
+    keys: JWK[];
+}
+interface PublicKeyToJWKOptions {
+    kid: string;
+    use?: 'sig' | 'enc';
+    alg?: 'EdDSA' | 'ES256';
+}
+/**
+ * Convert a public CryptoKey into a JWK. The `kid` is required so callers
+ * can match keys against the `kid` header on signed tokens. `alg` defaults
+ * to the algorithm implied by the key type (`EdDSA` for Ed25519, `ES256`
+ * for P-256).
+ */
+declare function publicKeyToJWK(publicKey: CryptoKey, options: PublicKeyToJWKOptions): Promise<JWK>;
+/** Wrap an array of JWKs in the JWKS envelope. */
+declare function buildJWKS(keys: JWK[]): JWKS;
+interface JWKSResolverOptions {
+    /** How long a fetched JWKS is cached in memory before refetch. Default 1 hour. */
+    cacheMaxAgeMs?: number;
+    /** How long a fetched JWKS is reused if a refetch fails. Default 24 hours. */
+    cooldownMs?: number;
+    /** Custom fetch implementation; defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * Allow non-https:// JWKS URLs. Off by default because APOA mandates TLS
+     * for all communication (SPEC §13.2). Use only for local development.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Create a KeyResolver backed by a remote JWKS endpoint. The resolver fetches
+ * `url`, caches the response, and returns the matching public key for a
+ * given `kid` claim. Used in conjunction with `validateToken`'s `keyResolver`
+ * option so a relying party can verify tokens signed by keys it discovers
+ * at runtime.
+ */
+declare function createJWKSResolver(url: string, options?: JWKSResolverOptions): KeyResolver;
+
 /**
  * Create a configured APOA client.
  * Wires up RevocationStore and AuditStore so methods don't need explicit store params.
@@ -503,4 +596,4 @@ declare function verifyChain(chain: DelegationChain, store?: RevocationStore): P
  */
 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 };
+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 JWK, type JWKS, type JWKSResolverOptions, type KeyResolver, type LegalFramework, MemoryAuditStore, MemoryRevocationStore, MetadataValidationError, type MetadataValue, type OnRuleViolation, type Principal, type PublicKeyToJWKOptions, 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, buildJWKS, cascadeRevoke, checkConstraint, checkScope, createClient, createJWKSResolver, createToken, decodeHeader, delegate, generateKeyPair, getAuditTrail, getAuditTrailByService, getDelegationAncestorIds, isBeforeNotBefore, isExpired, isRevoked, logAction, matchScope, parseDefinition, parseScope, publicKeyToJWK, revoke, sign, signToken, validateToken, verify, verifyAttenuation, verifyChain, verifySignature };