@zanii/mandate-verify-core 0.2.0 → 0.3.0

package/README.md

@@ -114,6 +114,36 @@ without a full request.
 
 Supply root-to-nearest-parent entries as `{ mandate, statusList }` with each parent's signed status envelope and independently configured root trust. Every link binds the parent ID, authorized child issuer, validity, depth and exact logical status-list reference. Numeric status claims, per-item key overrides and chains embedded in the action request do not establish authority. Supported references are the logical list ID or its `urn:zanii:status:` encoding; arbitrary URI suffixes do not bind a list. Stable-DID parent/status keys can be resolved through server-owned `resolveMandatePublicKey` and `resolveStatusPublicKey` pin callbacks; request- or artifact-supplied callbacks are not trusted context.
 
+## Root passports
+
+`verifyPassport` checks an agent's mandate all the way up to a root authority (for example a
+free zone), offline. The root signs one passport mandate to the firm's issuer DID. The firm then
+issues its own tree (company, role, release, instance) with ordinary delegation, so it never
+needs the root to sign anything else.
+
+```js
+import { verifyPassport } from '#verify-core';
+
+const result = verifyPassport({
+  passport, // signed by rootDid, agent = the firm's issuer DID, delegation allowed
+  passportStatusList, // the root's signed status list
+  rootDid,
+  mandate, // the agent instance's mandate
+  statusList,
+  delegationChain, // the firm's chain, top first: [{ mandate, statusList }, ...]
+  request: { agentDid, action, resource },
+});
+```
+
+It denies when the passport is not from `rootDid` (`PASSPORT_ROOT_UNTRUSTED`), is not a root
+(`PASSPORT_NOT_ROOT`), names a different issuer (`PASSPORT_ISSUER_MISMATCH`), does not allow
+issuing (`PASSPORT_NOT_DELEGABLE`), or when the firm's top mandate exceeds it
+(`PASSPORT_SCOPE_EXCEEDED`). Then it runs `verifyMandate` twice: the passport against the
+request with the root as the only trusted issuer (reasons tagged `scope: 'passport'`), and the
+firm's chain with the firm's issuer as the only trusted issuer. Revoking any level, from the
+passport down to the instance, denies everything below it. Budgets on the passport cannot be
+counted offline, so they give `review`, not `allow`.
+
 ## Offline trust bundles
 
 `createOfflineTrustBundle` in `#db` reads an initialized control store and exports
@@ -223,5 +253,11 @@ the connected deployment boundary.
 ## Test
 
 ```powershell
-node --test "tests/verify.test.js" "tests/delegation.test.js"
+node --test "tests/verify.test.js" "tests/delegation.test.js" "tests/passport.test.js"
 ```
+
+## Releases
+
+- **0.3.0**: `verifyPassport` checks an agent's mandate offline through the firm's own tree up to a
+  root authority (see "Root passports"). Additive; every 0.2.0 export is unchanged.
+- **0.2.0**: first public release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zanii/mandate-verify-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": "./src/index.js",
   "files": [

package/src/index.js

@@ -26,6 +26,7 @@ import { validityPolicyReason } from './policy.js';
 
 export { scopeSubsetReasons, inheritParentRestrictions } from './delegation.js';
 export { verifyOfflineTrustBundle } from './offline.js';
+export { verifyPassport } from './passport.js';
 export {
   evaluateConditions,
   verifyMandateAsync,

package/src/passport.js

@@ -0,0 +1,102 @@
+import { scopeSubsetReasons } from './delegation.js';
+import { verifyMandate } from './index.js';
+
+/**
+ * Verify an agent's passport chain up to a root authority (for example a free zone), offline.
+ *
+ * The root signs one passport mandate whose agent is the firm's issuer DID: that binds the
+ * firm's key under the root. The firm then issues its own tree (company, role, release,
+ * instance) with ordinary narrowing delegation, rooted in its issuer DID. This checks both:
+ *
+ * - the passport: signed by `rootDid`, a root itself, delegable, not revoked or expired in the
+ *   root's signed status list, and covering the requested action and resource;
+ * - the firm's chain and leaf mandate, with the firm's issuer as the only trusted root;
+ * - that the firm's top mandate stays within the passport (actions, resources, expiry, limits).
+ *
+ * Budgets on the passport cannot be checked offline (no usage counts), so they surface as
+ * `review`, never as `allow`.
+ */
+export function verifyPassport({
+  passport,
+  passportStatusList,
+  rootDid,
+  mandate,
+  statusList,
+  delegationChain = [],
+  request,
+  pins = {},
+  now = new Date(),
+  ...rest
+} = {}) {
+  const evaluatedAt = new Date(now).toISOString();
+  const deny = (code, message) => ({
+    verdict: 'deny',
+    mandateId: mandate?.id,
+    agentDid: request?.agentDid,
+    evaluatedAt,
+    reasons: [{ code, severity: 'hard', message }],
+    checks: [{ code, ok: false, severity: 'hard' }],
+  });
+  const firmTop = delegationChain[0]?.mandate ?? mandate;
+  const firmDid = firmTop?.issuer;
+  const subject = passport?.credentialSubject;
+
+  if (typeof rootDid !== 'string' || !rootDid)
+    return deny('PASSPORT_ROOT_MISSING', 'A root DID is required');
+  if (!subject || passport.issuer !== rootDid) {
+    return deny('PASSPORT_ROOT_UNTRUSTED', 'Passport is not issued by the configured root');
+  }
+  if (passport.parentMandateId)
+    return deny('PASSPORT_NOT_ROOT', 'A passport must be a root mandate');
+  if (typeof firmDid !== 'string' || subject.agent?.did !== firmDid) {
+    return deny('PASSPORT_ISSUER_MISMATCH', 'Passport does not name the issuer of this chain');
+  }
+  if (subject.delegation?.allowed !== true) {
+    return deny('PASSPORT_NOT_DELEGABLE', 'Passport does not allow its holder to issue');
+  }
+  const scope = scopeSubsetReasons(firmTop, passport);
+  if (scope.length > 0) return deny('PASSPORT_SCOPE_EXCEEDED', scope.join('; '));
+
+  const authority = verifyMandate({
+    mandate: passport,
+    statusList: passportStatusList,
+    request: { ...request, agentDid: firmDid },
+    pins: {
+      trustedIssuers: [rootDid],
+      requireStatus: true,
+      requireApproval: false,
+      requireCertification: false,
+      requireEvidence: false,
+      ...(pins.clockSkewSeconds === undefined ? {} : { clockSkewSeconds: pins.clockSkewSeconds }),
+      ...(pins.maxStatusAgeSeconds === undefined
+        ? {}
+        : { maxStatusAgeSeconds: pins.maxStatusAgeSeconds }),
+    },
+    now,
+  });
+  const chain = verifyMandate({
+    ...rest,
+    mandate,
+    statusList,
+    delegationChain,
+    request,
+    pins: { ...pins, trustedIssuers: [firmDid] },
+    now,
+  });
+
+  const verdicts = [authority.verdict, chain.verdict];
+  const verdict = ['error', 'deny', 'review'].find((v) => verdicts.includes(v)) ?? 'allow';
+  return {
+    ...chain,
+    verdict,
+    reasons: [
+      ...authority.reasons.map((reason) => ({ ...reason, scope: 'passport' })),
+      ...chain.reasons,
+    ],
+    checks: [
+      ...authority.checks.map((check) => ({ ...check, scope: 'passport' })),
+      ...chain.checks,
+    ],
+    passport: { id: passport.id, root: rootDid, holder: firmDid, verdict: authority.verdict },
+  };
+}