@agentcreds/sdk 0.1.1 → 0.2.0

package/index.d.ts

@@ -83,6 +83,18 @@ export interface ScopeInit {
   budgetUsd?: number
   maxDepth?: number
 }
+/**
+ * The RFC 8785 canonical form of a JSON-representable value.
+ *
+ * Throws rather than guessing for anything JSON cannot represent (`NaN`, a
+ * non-finite number, `undefined` inside an array): a canonicalizer that falls back
+ * emits a string the other side cannot reproduce, which presents as tampering on an
+ * untampered request. Integers past 2^53 have already been rounded by the time
+ * JavaScript hands them over - see the core's `jcs::precision_hazards` note.
+ */
+export declare function jcsCanonicalize(value: any): string
+/** The canonicalization profile name every runtime must agree on. */
+export declare function jcsProfile(): string
 /**
  * Issue a capability credential to `agentDid`, bound to a verified human
  * principal. The credential's validity is capped at the human's authorization
@@ -231,6 +243,42 @@ export declare class AdrCheckpoint {
   /** Parse a checkpoint from its JSON string. */
   static fromJson(s: string): AdrCheckpoint
 }
+/**
+ * An execution-time human-authorization designation carried inside the delegated
+ * authority (R10). Marks a `tool` as requiring human-approval evidence before
+ * execution. Monotone: derivations can add gates, never remove one. Mirrors the
+ * Python binding's `Gate`.
+ */
+export declare class Gate {
+  constructor(kind: string, tool: string)
+  /** A gate requiring anchor-signed human approval before `tool` may execute. */
+  static approval(tool: string): Gate
+  /**
+   * A gate requiring **approver-key-signed** approval (hybrid R10): the evidence
+   * is signed by the individual approver's key, verified against an
+   * org-anchor-signed `ApproverDirectory`.
+   */
+  static approvalKey(tool: string): Gate
+  get kind(): string
+  get tool(): string
+  toString(): string
+}
+/**
+ * A relying party's record of approval evidence already relied upon (R10
+ * one-time). `tryConsume` returns `true` the first time and `false` on re-use.
+ * In-process only: a multi-replica relying party needs a shared store with the
+ * same set-if-absent semantics. Mirrors the Python binding's `ConsumedApprovals`.
+ */
+export declare class ConsumedApprovals {
+  constructor()
+  /**
+   * Record `approvalId` as relied upon. `true` the first time; `false` on any
+   * subsequent call (already used - the action must be refused).
+   */
+  tryConsume(approvalId: string): boolean
+  /** Whether `approvalId` has already been relied upon. */
+  contains(approvalId: string): boolean
+}
 /**
  * One enrolled human approver: a `did:key` signing identity, roles, and an optional
  * expiry (`notAfterUnix`, unix seconds).
@@ -584,7 +632,14 @@ export declare class Scope {
   /**
    * True if `self` is permitted under `parent` (tools subset, budget and
    * depth not wider).
-   */
+   * Designate `tool` as requiring execution-time human approval (R10), builder
+   * style. Carried in the token; later hops can add gates, never remove one.
+   */
+  requireApproval(tool: string): Scope
+  /** Add execution-time gates (R10), builder style. */
+  withGates(gates: Array<Gate>): Scope
+  /** The execution-time gate designations in this scope (R10). */
+  get gates(): Array<Gate>
   isSubsetOf(parent: Scope): boolean
   /** The first tool in `self` that `parent` does not permit, if any. */
   firstWideningCapability(parent: Scope): string | null
@@ -673,6 +728,29 @@ export declare class DelegationToken {
    * status list as it stood then.
    */
   verifyRootedAt(action: Action, vc: CapabilityCredential, anchor: TrustAnchor, epochSeconds: number): void
+  /**
+   * The execution-time gate designations carried by this token (R10), read from
+   * the Biscuit's facts.
+   */
+  gates(): Array<Gate>
+  /**
+   * The gates designating `action.tool` - the human-authorization requirements
+   * to satisfy before executing it (R10).
+   */
+  requiredGates(action: Action): Array<Gate>
+  /**
+   * The R10 gate check **alone**, at `nowUnix`, without re-verifying the chain:
+   * for every gate designating `action.tool` (carried by this token or by `vc`),
+   * require carried, anchor-verified - or, for `approval-key`, directory-verified
+   * - principal-bound `evidence`, and return the `approvalId`s relied upon.
+   * Record them in a `ConsumedApprovals` and refuse a second reliance.
+   *
+   * Pair it with a chain check (`verifyRootedAt`, or a verified Presentation) run
+   * at the same instant; on its own it proves nothing about the token. A gate
+   * kind not in `recognizedKinds`, or one this verifier has no handler for, fails
+   * closed.
+   */
+  checkGatesAt(action: Action, vc: CapabilityCredential, evidence: Array<ApprovalEvidence>, directory: ApproverDirectory | undefined | null, anchor: TrustAnchor, recognizedKinds: Array<string>, nowUnix: number): Array<string>
   /**
    * Produce a proof of possession for `challenge`, signed by the token's
    * leaf agent. Only the leaf agent can do this.
@@ -826,6 +904,11 @@ export declare class OidcProvider {
    * `act` actor, they must match; `expectedNonce` is checked when supplied.
    */
   validateIdToken(idToken: string, expectedAgentDid?: string | undefined | null, expectedNonce?: string | undefined | null): VerifiedHumanPrincipal
+  /**
+   * `validateIdToken` judged **as of** `epochSeconds` rather than the wall clock:
+   * `exp` and `nbf` are checked against that instant (with the leeway).
+   */
+  validateIdTokenAt(idToken: string, epochSeconds: number, expectedAgentDid?: string | undefined | null, expectedNonce?: string | undefined | null): VerifiedHumanPrincipal
 }
 export declare class PopChallenge {
   /**
@@ -1017,8 +1100,15 @@ export declare class SignedTrustConfig {
   get entries(): Array<TrustEntry>
   /** Verify the config's signature against `anchor` (its issuer). */
   verify(anchor: TrustAnchor): void
+  /**
+   * `verify` judged **as of** `epochSeconds` (authenticity only; the instant is
+   * accepted so one `now` can be threaded through every check of a decision).
+   */
+  verifyAt(anchor: TrustAnchor, epochSeconds: number): void
   /** Whether the config is inside its validity window (unbounded = always current). */
   isCurrent(): boolean
+  /** `isCurrent` judged **as of** `epochSeconds` rather than the wall clock. */
+  isCurrentAt(epochSeconds: number): boolean
   /** The sealed expiry (rfc3339), or null if the config is unbounded. */
   get notAfter(): string | null
   /**
@@ -1029,6 +1119,8 @@ export declare class SignedTrustConfig {
    * member and never be believed.
    */
   verifyCurrent(anchor: TrustAnchor): void
+  /** `verifyCurrent` judged **as of** `epochSeconds` rather than the wall clock. */
+  verifyCurrentAt(anchor: TrustAnchor, epochSeconds: number): void
   /** The config as a JSON string (the persisted artifact). */
   toJson(): string
   /** Parse a config from its JSON string. */
@@ -1127,58 +1219,107 @@ export declare class KeyHistory {
   seal(current: TrustAnchor, version: number, notAfterUnix?: number | undefined | null): void
   /** Whether the sealed history is still inside its validity window. */
   isCurrent(): boolean
+  /** `isCurrent` judged **as of** `epochSeconds` rather than the wall clock. */
+  isCurrentAt(epochSeconds: number): boolean
   /** Verify the chain and the seal under the current key (authenticity only). */
   verifySealed(trustedRootDid: string): string
   /** Verify authenticity **and** freshness - what a relying party should use. */
   verifyCurrent(trustedRootDid: string): string
+  /** `verifyCurrent` judged **as of** `epochSeconds` rather than the wall clock. */
+  verifyCurrentAt(trustedRootDid: string, epochSeconds: number): string
   /** The DIDs still trusted for issuance (the chain minus the repudiations). */
   activeDids(): Array<string>
   /** The DIDs withdrawn from issuance. */
   repudiated(): Array<string>
   authorizeIssuer(trustedRootDid: string, issuerDid: string): TrustAnchor
+  /** `authorizeIssuer` judged **as of** `epochSeconds` rather than the wall clock. */
+  authorizeIssuerAt(trustedRootDid: string, issuerDid: string, epochSeconds: number): TrustAnchor
   /** Serialize the history to JSON (the portable artifact relying parties follow). */
   toJson(): string
   /** Parse a history from JSON. */
   static fromJson(s: string): KeyHistory
 }
 /**
- * An SD-JWT capability credential in compact form. The issuer hands the whole
- * thing to the holder; the holder calls `present` to reveal a subset.
+ * A capability credential issued as an **SD-JWT VC**, in compact form. The issuer
+ * hands the whole thing (issuer JWS plus every disclosure) to the holder; the
+ * holder calls `present` to reveal a subset of the advisory claims. Authority
+ * claims (tools, resources, budget, depth, autonomy, on-behalf-of, gates,
+ * accountability) are always disclosed - a verifier decides on them.
  */
 export declare class SdJwt {
   /**
-   * Issue an SD-JWT whose disclosable claims are the fields of `claims`
-   * (tools, budget, depth, autonomy, and the optional model/artifact/
-   * authorizer fields when present).
+   * Issue an SD-JWT VC for `claims`. The credential's lifetime is
+   * `claims.validForSecs`; the advisory claims that are set (`modelVersion`,
+   * `artifactHash`, `authorizedBy`) become selectively disclosable.
+   */
+  static fromCapability(anchor: TrustAnchor, subjectDid: string, claims: CapabilityClaims, revocation?: CredentialStatus | undefined | null): SdJwt
+  /** Wrap an already-issued SD-JWT VC `CapabilityCredential`. */
+  static fromCredential(credential: CapabilityCredential): SdJwt
+  /**
+   * Parse a compact SD-JWT VC (e.g. one received from an issuer). Disclosures
+   * are digest-checked against the signed `_sd` set here; the issuer signature is
+   * checked by `verifyPresentation` / `credential.verify`.
    */
-  static fromCapability(anchor: TrustAnchor, subjectDid: string, claims: CapabilityClaims, validForSecs: number): SdJwt
-  /** Parse a compact SD-JWT (e.g. one received from an issuer). */
   static parse(s: string): SdJwt
   /** The full compact serialization to hand to the holder. */
   asStr(): string
-  /** The names of the claims this SD-JWT can disclose. */
+  /**
+   * The names of the claims this SD-JWT can still disclose or withhold - only
+   * advisory metadata, never an authority claim.
+   */
   disclosableClaims(): Array<string>
   /**
-   * Holder side: a presentation revealing only the named claims (plus the
-   * always-disclosed registered claims). Unknown names are ignored.
+   * Holder side: a presentation carrying only the named disclosures. Authority
+   * claims are always present; a withheld advisory claim is absent from the bytes
+   * and cryptographically unrecoverable. Unknown names are ignored.
    */
   present(disclose: Array<string>): string
   /**
-   * Verifier side: verify a presentation against the issuer `anchor`,
-   * returning the disclosed claims. Throws on a bad signature, expiry, or a
-   * disclosure not covered by the signed `_sd` set.
+   * Holder side: `present` plus a holder-signed KB-JWT proving the presenter
+   * controls the credential's confirmation key (the subject's `did:key`).
+   * `audience` and `nonce` come from the verifier.
+   */
+  presentWithKeyBinding(holder: AgentIdentity, audience: string, nonce: string, disclose: Array<string>): string
+  /** The underlying credential (usable with `DelegationToken.verifyRooted`). */
+  get credential(): CapabilityCredential
+  /**
+   * Verifier side: parse a presentation, verify the issuer JWS against `anchor`
+   * (as of `nowUnix` if given, else the wall clock), and return the disclosed
+   * credential. Throws on a bad signature, expiry, an issuer other than the
+   * anchor, or a disclosure not covered by the signed `_sd` set.
    */
-  static verifyPresentation(presentation: string, anchor: TrustAnchor): DisclosedCredential
+  static verifyPresentation(presentation: string, anchor: TrustAnchor, nowUnix?: number | undefined | null): DisclosedCredential
+  toString(): string
 }
-/** The result of verifying an SD-JWT presentation. */
+/**
+ * The result of verifying an SD-JWT VC presentation: the full credential as the
+ * verifier sees it - authority claims always present, advisory claims present only
+ * if the holder disclosed them (a withheld one reads as `null`).
+ */
 export declare class DisclosedCredential {
   get issuer(): string
   get subject(): string
+  /** The SD-JWT VC `vct` (verifiable credential type). */
   get vct(): string
   get issuedAt(): string
   get expiresAt(): string
-  /** The disclosed claims as a JSON object string (name -> value). */
+  /** The names of the advisory claims the holder disclosed. */
+  get disclosed(): Array<string>
+  /**
+   * The verified claims as a JSON object string. Authority claims are always
+   * present; a withheld advisory claim is `null`.
+   */
   get disclosedJson(): string
+  /** The verified claims. */
+  claims(): CapabilityClaims
+  /** The verified credential, for the anchor-rooted token check. */
+  get credential(): CapabilityCredential
+  /**
+   * Verify the KB-JWT appended by `SdJwt.presentWithKeyBinding`: signed by the
+   * credential subject's key, bound to exactly this presentation, and matching the
+   * verifier's `audience` and `nonce`.
+   */
+  verifyKeyBinding(audience: string, nonce: string): void
 }
 /** A parsed SPIFFE ID (`spiffe://<trust_domain><path>`). */
 export declare class SpiffeId {
@@ -1204,6 +1345,8 @@ export declare class SpiffeTrustBundle {
   addP256Key(publicKey: Buffer, kid?: string | undefined | null): void
   /** Validate a JWT-SVID against this bundle, optionally requiring `expectedAudience`. */
   validateJwtSvid(jwt: string, expectedAudience?: string | undefined | null): ValidatedSvid
+  /** `validateJwtSvid` judged **as of** `epochSeconds` rather than the wall clock. */
+  validateJwtSvidAt(jwt: string, epochSeconds: number, expectedAudience?: string | undefined | null): ValidatedSvid
   /**
    * Export this bundle as a JWKS document (the portable WIMSE trust-bundle
    * exchange form) for peers to import.

package/index.js

@@ -310,11 +310,13 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { AuthzDecision, AdrStream, AdrCheckpoint, ApproverEntry, ApproverDirectory, ApprovalEvidence, AuditLog, AuditCompositor, EvidenceReport, EvidenceBundle, IdentityConfig, DelegationConfig, TrustConfig, AgentCredsConfig, CapabilityClaims, CredentialStatus, LinkedDataProof, CapabilityCredential, OwnershipRecord, Scope, Action, ChainEntry, DelegationChain, DelegationToken, PublicKey, VerificationMethod, DidDocument, AgentIdentity, TrustAnchor, InMemoryResolver, VerifiedHumanPrincipal, OidcProvider, issueOnBehalfOf, PopChallenge, ProofOfPossession, Presentation, HumanIdentity, TrustEntry, TrustRegistry, SignedTrustConfig, defaultListSize, RevocationList, RevocationRegistry, RotationStatement, KeyHistory, SdJwt, DisclosedCredential, SpiffeId, ValidatedSvid, SpiffeTrustBundle, issueFromSvid, MockOrg, MockAgent, FederationBridge, FederatedIdentity, version } = nativeBinding
+const { AuthzDecision, AdrStream, AdrCheckpoint, Gate, ConsumedApprovals, ApproverEntry, ApproverDirectory, ApprovalEvidence, AuditLog, AuditCompositor, EvidenceReport, EvidenceBundle, IdentityConfig, DelegationConfig, TrustConfig, AgentCredsConfig, CapabilityClaims, CredentialStatus, LinkedDataProof, CapabilityCredential, OwnershipRecord, Scope, Action, ChainEntry, DelegationChain, DelegationToken, PublicKey, VerificationMethod, DidDocument, AgentIdentity, TrustAnchor, InMemoryResolver, jcsCanonicalize, jcsProfile, VerifiedHumanPrincipal, OidcProvider, issueOnBehalfOf, PopChallenge, ProofOfPossession, Presentation, HumanIdentity, TrustEntry, TrustRegistry, SignedTrustConfig, defaultListSize, RevocationList, RevocationRegistry, RotationStatement, KeyHistory, SdJwt, DisclosedCredential, SpiffeId, ValidatedSvid, SpiffeTrustBundle, issueFromSvid, MockOrg, MockAgent, FederationBridge, FederatedIdentity, version } = nativeBinding
 
 module.exports.AuthzDecision = AuthzDecision
 module.exports.AdrStream = AdrStream
 module.exports.AdrCheckpoint = AdrCheckpoint
+module.exports.Gate = Gate
+module.exports.ConsumedApprovals = ConsumedApprovals
 module.exports.ApproverEntry = ApproverEntry
 module.exports.ApproverDirectory = ApproverDirectory
 module.exports.ApprovalEvidence = ApprovalEvidence
@@ -342,6 +344,8 @@ module.exports.DidDocument = DidDocument
 module.exports.AgentIdentity = AgentIdentity
 module.exports.TrustAnchor = TrustAnchor
 module.exports.InMemoryResolver = InMemoryResolver
+module.exports.jcsCanonicalize = jcsCanonicalize
+module.exports.jcsProfile = jcsProfile
 module.exports.VerifiedHumanPrincipal = VerifiedHumanPrincipal
 module.exports.OidcProvider = OidcProvider
 module.exports.issueOnBehalfOf = issueOnBehalfOf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcreds/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Verifiable, attenuable delegation for AI agents - org-rooted and verified offline",
   "main": "index.js",
   "types": "index.d.ts",
@@ -28,7 +28,7 @@
     "build:debug": "napi build --platform",
     "docs": "typedoc",
     "prepublishOnly": "napi prepublish -t npm",
-    "test": "node examples/quickstart.js && node --test test/conformance.test.js test/accountability.test.js",
+    "test": "node examples/quickstart.js && node --test test/conformance.test.js test/accountability.test.js test/as_of.test.js",
     "test:conformance": "node --test test/conformance.test.js",
     "version": "napi version"
   },
@@ -37,9 +37,9 @@
     "typedoc": "^0.25.0"
   },
   "optionalDependencies": {
-    "@agentcreds/sdk-win32-x64-msvc": "0.1.1",
-    "@agentcreds/sdk-darwin-x64": "0.1.1",
-    "@agentcreds/sdk-linux-x64-gnu": "0.1.1",
-    "@agentcreds/sdk-darwin-arm64": "0.1.1"
+    "@agentcreds/sdk-win32-x64-msvc": "0.2.0",
+    "@agentcreds/sdk-darwin-x64": "0.2.0",
+    "@agentcreds/sdk-linux-x64-gnu": "0.2.0",
+    "@agentcreds/sdk-darwin-arm64": "0.2.0"
   }
 }