@ixo/ucan 1.1.1 → 1.2.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @ixo/ucan@1.1.1 build /home/runner/work/qiforge/qiforge/packages/ucan
+> @ixo/ucan@1.2.0 build /home/runner/work/qiforge/qiforge/packages/ucan
 > tsc
 

package/README.md

@@ -74,7 +74,7 @@ const validator = await createUCANValidator({
 });
 ```
 
-### 3. Protect a Route
+### 3. Protect a Route (Invocation)
 
 ```typescript
 app.post('/employees', async (req, res) => {
@@ -99,6 +99,37 @@ app.post('/employees', async (req, res) => {
 });
 ```
 
+### 3b. Validate a Delegation
+
+Use `validateDelegation()` to verify a standalone delegation token — e.g. when a client sends a delegation in a header alongside a traditional auth mechanism. This verifies the cryptographic signature chain, audience, and expiration without requiring a capability definition.
+
+```typescript
+app.use(async (req, res, next) => {
+  const delegationHeader = req.headers['x-ucan-delegation'];
+  if (!delegationHeader) return next();
+
+  const result = await validator.validateDelegation(delegationHeader);
+
+  if (!result.ok) {
+    console.warn(`Delegation invalid: [${result.error?.code}] ${result.error?.message}`);
+    return next();
+  }
+
+  // result.invoker — issuer DID (who granted the delegation)
+  // result.capability — first capability in the delegation
+  // result.expiration — effective expiration across the proof chain
+  // result.proofChain — e.g. ["did:ixo:root", "did:ixo:user"]
+
+  req.ucanDelegation = {
+    issuer: result.invoker,
+    capability: result.capability,
+    expiration: result.expiration,
+  };
+
+  next();
+});
+```
+
 ### 4. Create & Use a Delegation (Client)
 
 ```typescript
@@ -183,18 +214,29 @@ Create a framework-agnostic validator.
 | `didResolver`     | `DIDKeyResolver`  | Resolver for non-`did:key` DIDs       |
 | `invocationStore` | `InvocationStore` | Custom store for replay protection    |
 
+#### Methods
+
+| Method                                                              | Description                                                   |
+| ------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `validate(invocationBase64, capabilityDef, resource)`               | Validate an invocation against a capability definition        |
+| `validateDelegation(delegationBase64)`                              | Validate a standalone delegation (signature, audience, chain) |
+
+**`validate()`** validates a full invocation — checks signature, capability matching, caveats, replay protection, and resource authorization.
+
+**`validateDelegation()`** validates a standalone delegation token — verifies the cryptographic signature of every delegation in the proof chain, checks audience matches `serverDid`, validates expiration, and ensures chain consistency (each proof's audience matches the child delegation's issuer). Supports `did:key` issuers natively and non-`did:key` issuers (e.g. `did:ixo`) via the configured `didResolver`.
+
 #### `ValidateResult`
 
-The `validator.validate()` method returns a `ValidateResult`:
+Both methods return a `ValidateResult`:
 
 | Field        | Type                                     | Description                                                                                          |
 | ------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | `ok`         | `boolean`                                | Whether validation succeeded                                                                         |
-| `invoker`    | `string`                                 | DID of the invoker (on success)                                                                      |
+| `invoker`    | `string`                                 | DID of the invoker/issuer (on success)                                                               |
 | `capability` | `object`                                 | Validated capability with `can`, `with`, and optional `nb` caveats (on success)                      |
 | `expiration` | `number \| undefined`                    | Effective expiration (Unix seconds) — the earliest across the delegation chain. Undefined = never.   |
 | `proofChain` | `string[] \| undefined`                  | Delegation path from root issuer to invoker, e.g. `["did:key:root", "did:key:alice", "did:key:bob"]` |
-| `facts`      | `Record<string, unknown>[] \| undefined` | Facts attached to the invocation. Undefined if none.                                                 |
+| `facts`      | `Record<string, unknown>[] \| undefined` | Facts attached to the invocation/delegation. Undefined if none.                                      |
 | `error`      | `object`                                 | Error with `code` and `message` (on failure)                                                         |
 
 Error codes: `INVALID_FORMAT`, `INVALID_SIGNATURE`, `UNAUTHORIZED`, `REPLAY`, `EXPIRED`, `CAVEAT_VIOLATION`.
@@ -293,7 +335,7 @@ pnpm test          # Run unit tests (vitest)
 pnpm test:ucan     # Run interactive test script with full UCAN flow
 ```
 
-The unit tests cover proof chain construction, expiration computation, facts pass-through, validation failures, caveat enforcement, and replay protection.
+The unit tests cover proof chain construction, expiration computation, facts pass-through, validation failures, caveat enforcement, replay protection, and delegation validation (signature verification, audience checks, expiration, tampered signatures, proof chain consistency, and `did:ixo` support).
 
 ## License
 

package/dist/did/web-resolver.d.ts

@@ -0,0 +1,7 @@
+import type { DIDKeyResolver } from '../types.js';
+export interface WebDIDResolverConfig {
+    fetch?: typeof globalThis.fetch;
+    fallbackToHttp?: boolean;
+}
+export declare function createWebDIDResolver(config?: WebDIDResolverConfig): DIDKeyResolver;
+//# sourceMappingURL=web-resolver.d.ts.map

package/dist/did/web-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-resolver.d.ts","sourceRoot":"","sources":["../../src/did/web-resolver.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAU,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAEhC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAwBD,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,cAAc,CAiGhB"}

package/dist/did/web-resolver.js

@@ -0,0 +1,78 @@
+export function createWebDIDResolver(config) {
+    const fetchFn = config?.fetch ?? globalThis.fetch;
+    return async (did) => {
+        if (!did.startsWith('did:web:')) {
+            return {
+                error: {
+                    name: 'DIDKeyResolutionError',
+                    did,
+                    message: `Cannot resolve ${did}: not a did:web identifier`,
+                },
+            };
+        }
+        try {
+            const parts = did.slice('did:web:'.length).split(':');
+            const domain = decodeURIComponent(parts[0]);
+            const pathSegments = parts.slice(1).map(decodeURIComponent);
+            const path = pathSegments.length > 0
+                ? `/${pathSegments.join('/')}/did.json`
+                : '/.well-known/did.json';
+            const httpsUrl = `https://${domain}${path}`;
+            let response = null;
+            let fetchUrl = httpsUrl;
+            try {
+                response = await fetchFn(httpsUrl);
+            }
+            catch (httpsError) {
+                if (config?.fallbackToHttp) {
+                    fetchUrl = `http://${domain}${path}`;
+                    response = await fetchFn(fetchUrl);
+                }
+                else {
+                    throw httpsError;
+                }
+            }
+            if (!response.ok && config?.fallbackToHttp && fetchUrl === httpsUrl) {
+                fetchUrl = `http://${domain}${path}`;
+                response = await fetchFn(fetchUrl);
+            }
+            if (!response.ok) {
+                return {
+                    error: {
+                        name: 'DIDKeyResolutionError',
+                        did,
+                        message: `Failed to fetch DID document from ${fetchUrl}: HTTP ${response.status}`,
+                    },
+                };
+            }
+            const doc = (await response.json());
+            const keys = [];
+            for (const vm of doc.verificationMethod ?? []) {
+                if (vm.type.includes('Ed25519') &&
+                    vm.publicKeyMultibase?.startsWith('z')) {
+                    keys.push(`did:key:${vm.publicKeyMultibase}`);
+                }
+            }
+            if (keys.length === 0) {
+                return {
+                    error: {
+                        name: 'DIDKeyResolutionError',
+                        did,
+                        message: `No valid Ed25519 verification methods found in DID document for ${did}`,
+                    },
+                };
+            }
+            return { ok: keys };
+        }
+        catch (error) {
+            return {
+                error: {
+                    name: 'DIDKeyResolutionError',
+                    did,
+                    message: `Failed to resolve ${did}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                },
+            };
+        }
+    };
+}
+//# sourceMappingURL=web-resolver.js.map

package/dist/did/web-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-resolver.js","sourceRoot":"","sources":["../../src/did/web-resolver.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { defineCapability, Schema, type DefineCapabilityOptions, } from './capab
 export { createUCANValidator, type CreateValidatorOptions, type ValidateResult, type UCANValidator, } from './validator/validator.js';
 export { generateKeypair, parseSigner, signerFromMnemonic, createDelegation, createInvocation, serializeInvocation, serializeDelegation, parseDelegation, type Signer, type Delegation, type Capability, type Fact, } from './client/create-client.js';
 export { createIxoDIDResolver, createCompositeDIDResolver, type IxoDIDResolverConfig, } from './did/ixo-resolver.js';
+export { createWebDIDResolver, type WebDIDResolverConfig, } from './did/web-resolver.js';
 export { InMemoryInvocationStore, createInvocationStore, } from './store/memory.js';
 export declare const VERSION = "1.0.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAMtD,YAAY,EACV,MAAM,EACN,MAAM,EACN,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,gBAAgB,EAChB,MAAM,EACN,KAAK,uBAAuB,GAC7B,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EACL,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,GACV,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAM3B,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAMtD,YAAY,EACV,MAAM,EACN,MAAM,EACN,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,gBAAgB,EAChB,MAAM,EACN,KAAK,uBAAuB,GAC7B,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EACL,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,GACV,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,oBAAoB,EACpB,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAM3B,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ export { defineCapability, Schema, } from './capabilities/capability.js';
 export { createUCANValidator, } from './validator/validator.js';
 export { generateKeypair, parseSigner, signerFromMnemonic, createDelegation, createInvocation, serializeInvocation, serializeDelegation, parseDelegation, } from './client/create-client.js';
 export { createIxoDIDResolver, createCompositeDIDResolver, } from './did/ixo-resolver.js';
+export { createWebDIDResolver, } from './did/web-resolver.js';
 export { InMemoryInvocationStore, createInvocationStore, } from './store/memory.js';
 export const VERSION = '1.0.0';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAqBtD,OAAO,EACL,gBAAgB,EAChB,MAAM,GAEP,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EACL,mBAAmB,GAIpB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAKhB,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,GAE3B,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAM3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,eAAe,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAqBtD,OAAO,EACL,gBAAgB,EAChB,MAAM,GAEP,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EACL,mBAAmB,GAIpB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAKhB,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EACL,oBAAoB,EACpB,0BAA0B,GAE3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,oBAAoB,GAErB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAM3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}