@apoa/core 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -235,6 +235,35 @@ interface APOAClientOptions {
     keyResolver?: KeyResolver;
     defaultSigningOptions?: Partial<SigningOptions>;
 }
+/** Options for the application-facing APOA facade. */
+interface APOAOptions extends Omit<APOAClientOptions, 'defaultSigningOptions'> {
+    privateKey?: CryptoKey;
+    algorithm?: 'EdDSA' | 'ES256';
+    kid?: string;
+}
+/** Duration string for convenience expiry fields, e.g. `15m`, `2h`, `30d`. */
+type DurationString = `${number}${'s' | 'm' | 'h' | 'd'}`;
+/** One-service grant input accepted by the application-facing facade. */
+interface SimpleGrantInput {
+    principal: string | Principal;
+    agent: string | Agent;
+    service?: string;
+    scopes?: string[];
+    services?: ServiceAuthorization[];
+    constraints?: ConstraintMap;
+    rules?: Rule[];
+    expires?: Date | string;
+    expiresIn?: DurationString;
+    revocable?: boolean;
+    delegatable?: boolean;
+    maxDelegationDepth?: number;
+    metadata?: TokenMetadata;
+    accessMode?: AccessMode;
+    browserConfig?: BrowserSessionConfig;
+    apiConfig?: APIAccessConfig;
+    agentProvider?: AgentProvider;
+    legal?: LegalFramework;
+}
 /** The configured APOA client. */
 interface APOAClient {
     createToken(definition: APOADefinition, options?: SigningOptions): Promise<APOAToken>;
@@ -520,6 +549,24 @@ declare function delegate(parentToken: APOAToken, childDef: DelegationDefinition
  */
 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;
@@ -578,4 +625,25 @@ declare function createJWKSResolver(url: string, options?: JWKSResolverOptions):
  */
 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 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, isBeforeNotBefore, isExpired, isRevoked, logAction, matchScope, parseDefinition, parseScope, publicKeyToJWK, revoke, sign, signToken, validateToken, verify, verifyAttenuation, verifyChain, verifySignature };
+/**
+ * Application-facing APOA facade.
+ *
+ * This keeps the protocol-level APIs intact while giving app developers a
+ * smaller first path: configure once, then use namespaced resources.
+ */
+declare class APOA {
+    private readonly client;
+    readonly tokens: {
+        create: (definition: APOADefinition, options?: SigningOptions) => Promise<APOAToken>;
+        createGrant: (input: SimpleGrantInput, options?: SigningOptions) => Promise<APOAToken>;
+        validate: (token: string | APOAToken, options?: Omit<ValidationOptions, 'revocationStore'>) => Promise<ValidationResult>;
+        parse: (input: string, format?: 'yaml' | 'json') => APOADefinition;
+    };
+    readonly authorizations: {
+        check: (token: APOAToken, service: string, action: string, options?: Omit<AuthorizeOptions, 'revocationStore' | 'auditStore'>) => Promise<AuthorizationResult>;
+    };
+    constructor(options?: APOAOptions);
+    generateKeyPair(algorithm?: 'EdDSA' | 'ES256'): Promise<CryptoKeyPair>;
+}
+
+export { type APIAccessConfig, APOA, type APOAClient, type APOAClientOptions, type APOADefinition, APOAError, type APOAOptions, 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 DurationString, 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, type SimpleGrantInput, 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

@@ -235,6 +235,35 @@ interface APOAClientOptions {
     keyResolver?: KeyResolver;
     defaultSigningOptions?: Partial<SigningOptions>;
 }
+/** Options for the application-facing APOA facade. */
+interface APOAOptions extends Omit<APOAClientOptions, 'defaultSigningOptions'> {
+    privateKey?: CryptoKey;
+    algorithm?: 'EdDSA' | 'ES256';
+    kid?: string;
+}
+/** Duration string for convenience expiry fields, e.g. `15m`, `2h`, `30d`. */
+type DurationString = `${number}${'s' | 'm' | 'h' | 'd'}`;
+/** One-service grant input accepted by the application-facing facade. */
+interface SimpleGrantInput {
+    principal: string | Principal;
+    agent: string | Agent;
+    service?: string;
+    scopes?: string[];
+    services?: ServiceAuthorization[];
+    constraints?: ConstraintMap;
+    rules?: Rule[];
+    expires?: Date | string;
+    expiresIn?: DurationString;
+    revocable?: boolean;
+    delegatable?: boolean;
+    maxDelegationDepth?: number;
+    metadata?: TokenMetadata;
+    accessMode?: AccessMode;
+    browserConfig?: BrowserSessionConfig;
+    apiConfig?: APIAccessConfig;
+    agentProvider?: AgentProvider;
+    legal?: LegalFramework;
+}
 /** The configured APOA client. */
 interface APOAClient {
     createToken(definition: APOADefinition, options?: SigningOptions): Promise<APOAToken>;
@@ -520,6 +549,24 @@ declare function delegate(parentToken: APOAToken, childDef: DelegationDefinition
  */
 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;
@@ -578,4 +625,25 @@ declare function createJWKSResolver(url: string, options?: JWKSResolverOptions):
  */
 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 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, isBeforeNotBefore, isExpired, isRevoked, logAction, matchScope, parseDefinition, parseScope, publicKeyToJWK, revoke, sign, signToken, validateToken, verify, verifyAttenuation, verifyChain, verifySignature };
+/**
+ * Application-facing APOA facade.
+ *
+ * This keeps the protocol-level APIs intact while giving app developers a
+ * smaller first path: configure once, then use namespaced resources.
+ */
+declare class APOA {
+    private readonly client;
+    readonly tokens: {
+        create: (definition: APOADefinition, options?: SigningOptions) => Promise<APOAToken>;
+        createGrant: (input: SimpleGrantInput, options?: SigningOptions) => Promise<APOAToken>;
+        validate: (token: string | APOAToken, options?: Omit<ValidationOptions, 'revocationStore'>) => Promise<ValidationResult>;
+        parse: (input: string, format?: 'yaml' | 'json') => APOADefinition;
+    };
+    readonly authorizations: {
+        check: (token: APOAToken, service: string, action: string, options?: Omit<AuthorizeOptions, 'revocationStore' | 'auditStore'>) => Promise<AuthorizationResult>;
+    };
+    constructor(options?: APOAOptions);
+    generateKeyPair(algorithm?: 'EdDSA' | 'ES256'): Promise<CryptoKeyPair>;
+}
+
+export { type APIAccessConfig, APOA, type APOAClient, type APOAClientOptions, type APOADefinition, APOAError, type APOAOptions, 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 DurationString, 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, type SimpleGrantInput, 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.js

@@ -1137,6 +1137,37 @@ function checkAttenuation(parent, child, index, errors) {
   }
 }
 
+// src/delegation/ancestors.ts
+function getDelegationAncestorIds(input) {
+  const ids = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (value) => {
+    if (typeof value !== "string" || value.length === 0 || seen.has(value)) {
+      return;
+    }
+    seen.add(value);
+    ids.push(value);
+  };
+  const token = input;
+  const definition = hasDefinition(input) ? token.definition : input;
+  push(token.parentToken);
+  push(definition?.parentToken);
+  const chain = definition?.delegationChain;
+  if (Array.isArray(chain)) {
+    for (const link of chain) {
+      if (typeof link === "string") {
+        push(link);
+      } else if (link && typeof link === "object") {
+        push(link.parentTokenId);
+      }
+    }
+  }
+  return ids;
+}
+function hasDefinition(input) {
+  return Boolean(input && typeof input === "object" && "definition" in input);
+}
+
 // src/jwks/index.ts
 import * as jose3 from "jose";
 async function publicKeyToJWK(publicKey, options) {
@@ -1221,7 +1252,9 @@ function createClient(options) {
   const defaultSigningOptions = options?.defaultSigningOptions;
   function mergeSigningOptions(opts) {
     if (!opts && !defaultSigningOptions?.privateKey) {
-      throw new Error("No signing options provided and no defaultSigningOptions.privateKey configured");
+      throw new Error(
+        "APOA needs a private key to create tokens. Pass `privateKey` to `new APOA({ privateKey })`, configure `createClient({ defaultSigningOptions: { privateKey } })`, or pass signing options to `createToken(...)`."
+      );
     }
     return {
       ...defaultSigningOptions,
@@ -1282,7 +1315,147 @@ function createClient(options) {
     }
   };
 }
+
+// src/apoa.ts
+var APOA = class {
+  client;
+  tokens;
+  authorizations;
+  constructor(options = {}) {
+    const { privateKey, algorithm, kid, ...clientOptions } = options;
+    this.client = createClient({
+      ...clientOptions,
+      defaultSigningOptions: privateKey ? { privateKey, algorithm, kid } : void 0
+    });
+    this.tokens = {
+      create: (definition, signingOptions) => this.client.createToken(definition, signingOptions),
+      createGrant: async (input, signingOptions) => this.client.createToken(normalizeGrantInput(input), signingOptions),
+      validate: (token, validationOptions) => this.client.validateToken(token, validationOptions),
+      parse: (input, format) => this.client.parseDefinition(input, format)
+    };
+    this.authorizations = {
+      check: (token, service, action, authorizeOptions) => this.client.authorize(token, service, action, authorizeOptions)
+    };
+  }
+  async generateKeyPair(algorithm) {
+    return this.client.generateKeyPair(algorithm);
+  }
+};
+function normalizeGrantInput(input) {
+  const errors = [];
+  if (!input || typeof input !== "object") {
+    throw invalidGrantInput(["input must be an object"]);
+  }
+  const principal = normalizePrincipal(input.principal, errors);
+  const agent = normalizeAgent(input.agent, errors);
+  const services = normalizeServices(input, errors);
+  const expires = normalizeExpires(input, errors);
+  if (errors.length > 0 || !principal || !agent || services.length === 0 || !expires) {
+    throw invalidGrantInput(errors);
+  }
+  return {
+    principal,
+    agent,
+    services,
+    expires,
+    ...input.rules ? { rules: input.rules } : {},
+    ...input.revocable !== void 0 ? { revocable: input.revocable } : {},
+    ...input.delegatable !== void 0 ? { delegatable: input.delegatable } : {},
+    ...input.maxDelegationDepth !== void 0 ? { maxDelegationDepth: input.maxDelegationDepth } : {},
+    ...input.metadata ? { metadata: input.metadata } : {},
+    ...input.agentProvider ? { agentProvider: input.agentProvider } : {},
+    ...input.legal ? { legal: input.legal } : {}
+  };
+}
+function normalizePrincipal(principal, errors) {
+  if (typeof principal === "string" && principal.trim()) {
+    return { id: principal.trim() };
+  }
+  if (principal && typeof principal === "object" && principal.id) {
+    return principal;
+  }
+  errors.push("principal is required; pass a DID string or { id }");
+  return void 0;
+}
+function normalizeAgent(agent, errors) {
+  if (typeof agent === "string" && agent.trim()) {
+    return { id: agent.trim() };
+  }
+  if (agent && typeof agent === "object" && agent.id) {
+    return agent;
+  }
+  errors.push("agent is required; pass a DID string or { id }");
+  return void 0;
+}
+function normalizeServices(input, errors) {
+  if (input.services) {
+    if (!Array.isArray(input.services) || input.services.length === 0) {
+      errors.push("services must be a non-empty array when provided");
+      return [];
+    }
+    return input.services;
+  }
+  if (!input.service) {
+    errors.push("service is required unless services is provided");
+    return [];
+  }
+  if (!input.scopes || !Array.isArray(input.scopes) || input.scopes.length === 0) {
+    errors.push("scopes must be a non-empty array unless services is provided");
+    return [];
+  }
+  return [{
+    service: input.service,
+    scopes: input.scopes,
+    ...input.constraints ? { constraints: input.constraints } : {},
+    ...input.accessMode ? { accessMode: input.accessMode } : {},
+    ...input.browserConfig ? { browserConfig: input.browserConfig } : {},
+    ...input.apiConfig ? { apiConfig: input.apiConfig } : {}
+  }];
+}
+function normalizeExpires(input, errors) {
+  if (input.expires && input.expiresIn) {
+    errors.push("pass either expires or expiresIn, not both");
+    return void 0;
+  }
+  if (input.expires) {
+    return input.expires;
+  }
+  if (input.expiresIn) {
+    return parseDurationFromNow(input.expiresIn);
+  }
+  errors.push("expires or expiresIn is required");
+  return void 0;
+}
+function parseDurationFromNow(duration) {
+  const match = /^(\d+)([smhd])$/.exec(duration);
+  if (!match) {
+    throw invalidGrantInput([
+      `expiresIn must use a clear duration like '15m', '2h', or '30d'`
+    ]);
+  }
+  const amount = Number(match[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw invalidGrantInput(["expiresIn duration must be a positive integer"]);
+  }
+  const unitMs = {
+    s: 1e3,
+    m: 60 * 1e3,
+    h: 60 * 60 * 1e3,
+    d: 24 * 60 * 60 * 1e3
+  };
+  return new Date(Date.now() + amount * unitMs[match[2]]);
+}
+function invalidGrantInput(errors) {
+  return new Error(
+    [
+      "Invalid APOA grant input.",
+      ...errors.map((error) => `- ${error}`),
+      "Minimal shape: { principal, agent, service, scopes, expiresIn }"
+    ].join("\n")
+  );
+}
 export {
+  APOA,
   APOAError,
   AttenuationViolationError,
   ChainVerificationError,
@@ -1307,6 +1480,7 @@ export {
   generateKeyPair2 as generateKeyPair,
   getAuditTrail,
   getAuditTrailByService,
+  getDelegationAncestorIds,
   isBeforeNotBefore,
   isExpired,
   isRevoked,