@tinycloud/sdk-core 3.0.0-beta.17 → 3.0.0-beta.19

package/dist/index.cjs

@@ -421,6 +421,7 @@ __export(index_exports, {
   serviceError: () => import_sdk_services8.serviceError,
   sha256Base64Url: () => sha256Base64Url,
   shareCapabilityAllows: () => shareCapabilityAllows,
+  signCompactPolicyDescendant: () => signCompactPolicyDescendant,
   signCompactUcanAuthorization: () => signCompactUcanAuthorization,
   signCompactUcanRootAuthorization: () => signCompactUcanRootAuthorization,
   signLocationRecord: () => signLocationRecord,
@@ -4495,8 +4496,9 @@ async function signCompactUcanAuthorization(input) {
     throw new Error("compact invocation lifetime must be between one and 60 seconds");
   return signCompactUcan(input);
 }
+var MAX_POLICY_ROOT_SECONDS = 31 * 24 * 60 * 60;
 async function signCompactUcanRootAuthorization(input) {
-  if (input.notBefore >= input.expiresAt || input.expiresAt - input.notBefore > 31 * 24 * 60 * 60)
+  if (input.notBefore >= input.expiresAt || input.expiresAt - input.notBefore > MAX_POLICY_ROOT_SECONDS)
     throw new Error("compact policy root lifetime must be between one second and 31 days");
   return signCompactUcan({ ...input, proofs: [] });
 }
@@ -4531,7 +4533,7 @@ function createCompactPolicyInvocation(input) {
   const signature = import_ed255193.ed25519.sign(signingInput, input.privateKey);
   return parseCompactUcanAuthorization(`${protectedSegment}.${payloadSegment}.${encodeBase64Url2(signature)}`);
 }
-function createCompactPolicyDescendant(input) {
+function compactPolicyDescendantClaims(input) {
   const parent = parseCompactUcanAuthorization(input.parentAuthorization, input.parentCid);
   if (parent.payload.aud !== input.issuerDid) throw new Error("policy descendant issuer is not the parent audience");
   const parentFact = parent.payload.fct[0];
@@ -4539,29 +4541,53 @@ function createCompactPolicyDescendant(input) {
   if (!Number.isInteger(depth) || depth <= 0) throw new Error("policy descendant depth is exhausted");
   if (!compactAttenuationContains(parent.payload.att, input.attenuation))
     throw new Error("policy descendant exceeds the parent attenuation");
+  const now = Math.max(input.now ?? parent.payload.nbf + 1, parent.payload.nbf + 1);
+  const exp = Math.min(input.expiresAt ?? parent.payload.exp - 1, parent.payload.exp - 1);
+  if (exp <= now) throw new Error("policy parent has no strictly narrower validity window");
+  return {
+    parentCid: parent.cid,
+    fact: { ...parentFact, remainingRedelegationDepth: depth - 1 },
+    notBefore: now,
+    expiresAt: exp,
+    nonce: input.nonce ?? encodeBase64Url2(crypto.getRandomValues(new Uint8Array(16)))
+  };
+}
+function createCompactPolicyDescendant(input) {
+  const claims = compactPolicyDescendantClaims(input);
   const principal = input.issuerDid.split("#", 1)[0];
   const didMaterial = base58btc.decode(principal.slice("did:key:".length));
   const publicKey = import_ed255193.ed25519.getPublicKey(input.privateKey);
   if (didMaterial.length !== 34 || !equalBytes(publicKey, didMaterial.slice(2))) throw new Error("policy descendant signer does not bind issuer DID");
-  const now = Math.max(input.now ?? Math.floor(Date.now() / 1e3), parent.payload.nbf + 1);
-  const exp = Math.min(input.expiresAt ?? now + 60, now + 60, parent.payload.exp - 1);
-  if (exp <= now) throw new Error("policy parent has no strictly narrower validity window");
   const header = { alg: "EdDSA", jwk: { alg: "EdDSA", crv: "Ed25519", kty: "OKP", x: encodeBase64Url2(publicKey) }, typ: "JWT", ucv: "0.10.0" };
   const payload = {
     att: input.attenuation,
     aud: input.audienceDid,
-    exp,
-    fct: [{ ...parentFact, remainingRedelegationDepth: depth - 1 }],
+    exp: claims.expiresAt,
+    fct: [claims.fact],
     iss: input.issuerDid.includes("#") ? input.issuerDid : `${principal}#${principal.slice("did:key:".length)}`,
-    nbf: now,
-    nnc: input.nonce ?? encodeBase64Url2(crypto.getRandomValues(new Uint8Array(16))),
-    prf: [parent.cid]
+    nbf: claims.notBefore,
+    nnc: claims.nonce,
+    prf: [claims.parentCid]
   };
   const protectedSegment = encodeBase64Url2(new TextEncoder().encode(jcsCanonicalize(header)));
   const payloadSegment = encodeBase64Url2(new TextEncoder().encode(jcsCanonicalize(payload)));
   const signature = import_ed255193.ed25519.sign(new TextEncoder().encode(`${protectedSegment}.${payloadSegment}`), input.privateKey);
   return parseCompactUcanAuthorization(`${protectedSegment}.${payloadSegment}.${encodeBase64Url2(signature)}`);
 }
+async function signCompactPolicyDescendant(input) {
+  const claims = compactPolicyDescendantClaims(input);
+  return signCompactUcan({
+    issuerDid: input.issuerDid,
+    audienceDid: input.audienceDid,
+    attenuation: input.attenuation,
+    facts: [claims.fact],
+    proofs: [claims.parentCid],
+    notBefore: claims.notBefore,
+    expiresAt: claims.expiresAt,
+    nonce: claims.nonce,
+    sign: input.sign
+  });
+}
 function compactAttenuationContains(parent, child) {
   const selector = (value) => {
     if (value.length !== 1 || !isRecordValue(value[0])) return void 0;
@@ -4631,7 +4657,7 @@ function parsePolicySessionUcan(authorization, expectedProofs) {
     throw new Error("policy session UCAN fact is incomplete");
   if (hasV4AuditFactShape && (!LOWER_SHA256_HEX.test(fact.credentialIdAuditDigestHex) || !LOWER_SHA256_HEX.test(fact.presentationJtiAuditDigestHex)))
     throw new Error("policy session UCAN v4 audit facts are invalid");
-  if (fact.profile !== POLICY_SESSION_UCAN_V1_PROFILE || typeof fact.remainingRedelegationDepth !== "number" || !Number.isInteger(fact.remainingRedelegationDepth) || fact.remainingRedelegationDepth < 0 || fact.remainingRedelegationDepth > 8 || parsed.payload.exp - parsed.payload.nbf > 60 || parsed.payload.iss.split("#", 1)[0] !== fact.nodeAudience || parsed.payload.aud !== fact.recipientDid)
+  if (fact.profile !== POLICY_SESSION_UCAN_V1_PROFILE || typeof fact.remainingRedelegationDepth !== "number" || !Number.isInteger(fact.remainingRedelegationDepth) || fact.remainingRedelegationDepth < 0 || fact.remainingRedelegationDepth > 8 || parsed.payload.exp - parsed.payload.nbf > MAX_POLICY_ROOT_SECONDS || parsed.payload.iss.split("#", 1)[0] !== fact.nodeAudience || parsed.payload.aud !== fact.recipientDid)
     throw new Error("policy session UCAN fact is invalid");
   return {
     authorization,
@@ -5055,24 +5081,21 @@ async function admitPolicyCredentialV3(input) {
     policy,
     challenge
   });
-  const response = await fetchFn(
+  const response = await postPolicyDelegation(
+    fetchFn,
     new URL(`${policyRuntimeBasePath2(input.policyRuntimePath)}/delegations`, nodeOrigin),
     {
-      method: "POST",
-      redirect: "error",
-      signal: input.signal,
-      headers: { accept: "application/json", "content-type": "application/json" },
-      body: JSON.stringify({
-        policyCid: input.policyCid,
-        challengeId: challenge.challengeId,
-        nonce: challenge.nonce,
-        requirement: validateCredentialRequirement(input.requirement),
-        credential: envelopeFromVerified(input.credential),
-        accountAuthorizationCid,
-        credentialSpaceId,
-        presentation
-      })
-    }
+      policyCid: input.policyCid,
+      challengeId: challenge.challengeId,
+      nonce: challenge.nonce,
+      requirement: validateCredentialRequirement(input.requirement),
+      credential: envelopeFromVerified(input.credential),
+      accountAuthorizationCid,
+      credentialSpaceId,
+      presentation
+    },
+    requestedSessionExpiry(input.requestedExpiresAt, policy),
+    input.signal
   );
   if (!response.ok) throw new Error(`policy delegation rejected (${response.status})`);
   const value = record(await response.json(), "policy delegation");
@@ -5113,20 +5136,20 @@ async function admitPolicyCredentialV4(input) {
     policy,
     challenge
   });
-  const response = await fetchFn(new URL(`${policyRuntimeBasePath2(input.policyRuntimePath)}/delegations`, nodeOrigin), {
-    method: "POST",
-    redirect: "error",
-    signal: input.signal,
-    headers: { accept: "application/json", "content-type": "application/json" },
-    body: JSON.stringify({
+  const response = await postPolicyDelegation(
+    fetchFn,
+    new URL(`${policyRuntimeBasePath2(input.policyRuntimePath)}/delegations`, nodeOrigin),
+    {
       policyCid: input.policyCid,
       challengeId: challenge.challengeId,
       nonce: challenge.nonce,
       requirement: validateCredentialRequirement(input.requirement),
       credential: envelopeFromVerified(input.credential),
       presentation
-    })
-  });
+    },
+    requestedSessionExpiry(input.requestedExpiresAt, policy),
+    input.signal
+  );
   if (!response.ok) throw new Error(`policy delegation rejected (${response.status})`);
   const value = record(await response.json(), "policy delegation");
   if (value.admitted !== true || typeof value.sessionCid !== "string" || typeof value.authorization !== "string") throw new Error("policy delegation response is invalid");
@@ -5150,6 +5173,27 @@ async function admitPolicyCredentialV4(input) {
   input.signal?.throwIfAborted();
   return Object.freeze({ challenge, presentation, session, delegationImported: true });
 }
+function requestedSessionExpiry(requested, policy) {
+  const value = requested === void 0 ? policy.expiresAt : requested;
+  if (value === null || value === void 0) return void 0;
+  const seconds = Math.floor(Date.parse(value) / 1e3);
+  if (!Number.isFinite(seconds) || seconds <= Math.floor(Date.now() / 1e3) + 60) return void 0;
+  return new Date(seconds * 1e3).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+async function postPolicyDelegation(fetchFn, url, body, requestedExpiresAt, signal) {
+  const send = (payload) => fetchFn(url, {
+    method: "POST",
+    redirect: "error",
+    signal,
+    headers: { accept: "application/json", "content-type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+  if (requestedExpiresAt === void 0) return send(body);
+  const response = await send({ ...body, requestedExpiresAt });
+  if (response.status !== 422) return response;
+  await response.body?.cancel().catch(() => void 0);
+  return send(body);
+}
 function policyRuntimeBasePath2(value) {
   const path = value ?? "/policy/v3";
   if (!/^\/policy(?:\/[a-z0-9-]+)*$/.test(path)) {
@@ -11150,11 +11194,11 @@ var SharingService = class {
       }
       return result;
     };
-    const canSatisfyFromRegistry = this.findSuitableKeyForDelegation(
+    const canSatisfyFromRegistry = this.classifyDelegationAuthority(
       fullPath,
       actions,
       requestedExpiry
-    );
+    ) === "ok";
     if (canSatisfyFromRegistry) {
       const delegationResult = await this.createSessionDelegation(plainDID, fullPath, actions, expiry);
       const childDelegationActiveError = this.retiredGraphError();
@@ -11224,49 +11268,58 @@ var SharingService = class {
     return { ok: true, data: shareLink };
   }
   /**
-   * Check if any key in the registry can satisfy the delegation request.
-   * A key can satisfy if it has a delegation that:
-   * 1. Covers the required path (exact match or parent path)
-   * 2. Has all required actions
-   * 3. Has sufficient expiry (delegation.expiry >= requestedExpiry)
-   * 4. Allows sub-delegation
+   * Report, without side effects, whether this session's registry authority
+   * can issue the child delegation {@link generate} would create for the same
+   * `path`, `actions` and `expiry` (defaults and `pathPrefix` applied the
+   * same way):
+   *
+   * - `"ok"`: an uncaveated entry covers it.
+   * - `"caveated"`: only caveated entries cover it. SharingService cannot
+   *   carry signed ReCap caveats into a child delegation.
+   * - `"not-covered"`: no entry covers it, or there is no session.
+   *
+   * It does not consult `onRootDelegationNeeded`, so a signer-backed session
+   * may still generate when this is not `"ok"`.
+   */
+  preflightGenerate(params) {
+    if (!this.session || !params.path) return "not-covered";
+    const fullPath = this.pathPrefix ? `${this.pathPrefix}/${params.path}`.replace(/\/+/g, "/") : params.path;
+    return this.classifyDelegationAuthority(
+      fullPath,
+      params.actions ?? DEFAULT_READ_ACTIONS,
+      params.expiry ?? new Date(Date.now() + DEFAULT_EXPIRY_MS)
+    );
+  }
+  /**
+   * Classify the registry's authority for a child delegation. An entry
+   * satisfies it when it is in the session space, valid, lasts at least until
+   * `requestedExpiry`, allows sub-delegation, covers `path` (exact or parent)
+   * and grants every action. Satisfying entries with caveats are unusable.
    * @internal
    */
-  findSuitableKeyForDelegation(path, actions, requestedExpiry) {
-    const allKeys = this.registry.getAllKeys();
-    for (const key of allKeys) {
-      const delegations = this.registry.getDelegationsForKey(key.id);
-      for (const delegation of delegations) {
+  classifyDelegationAuthority(path, actions, requestedExpiry) {
+    let coveredOnlyByCaveated = false;
+    for (const key of this.registry.getAllKeys()) {
+      for (const delegation of this.registry.getDelegationsForKey(key.id)) {
         if (delegation.spaceId === void 0 || !spaceIdsEqual(delegation.spaceId, this.session?.spaceId ?? "")) {
           continue;
         }
-        if ((delegation.caveats?.length ?? 0) > 0) {
-          continue;
-        }
-        if (!this.registry.isDelegationValid(delegation)) {
-          continue;
-        }
-        if (delegation.expiry < requestedExpiry) {
-          continue;
-        }
-        if (delegation.allowSubDelegation === false) {
-          continue;
-        }
-        const delegationPath = delegation.path || "";
-        if (!this.pathMatches(delegationPath, path)) {
+        if (!this.registry.isDelegationValid(delegation)) continue;
+        if (delegation.expiry < requestedExpiry) continue;
+        if (delegation.allowSubDelegation === false) continue;
+        if (!this.pathMatches(delegation.path || "", path)) continue;
+        const delegationActions = delegation.actions || [];
+        if (!actions.every((action) => delegationActions.includes(action) || delegationActions.includes("*"))) {
           continue;
         }
-        const delegationActions = delegation.actions || [];
-        const hasAllActions = actions.every(
-          (action) => delegationActions.includes(action) || delegationActions.includes("*")
-        );
-        if (!hasAllActions) {
+        if ((delegation.caveats?.length ?? 0) > 0) {
+          coveredOnlyByCaveated = true;
           continue;
         }
-        return true;
+        return "ok";
       }
     }
-    return false;
+    return coveredOnlyByCaveated ? "caveated" : "not-covered";
   }
   retiredGraphError() {
     try {