was-teaching-server 0.9.1

package/dist/authorize.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-request authorization decision. Replaces the inline `handleZcapVerify`
+ * call in read handlers with a two-step decision: first try the capability
+ * invocation (if auth headers are present); if that does not grant access, fall
+ * back to the target's effective access-control policy (see policy.ts). Throws
+ * the same errors as `handleZcapVerify` when neither path authorizes the
+ * request. The decision is permissive: a policy can only broaden access, never
+ * deny a valid capability holder.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { IDID } from './types.js';
+/**
+ * Authorizes a request against a target, by capability invocation first and the
+ * effective access-control policy second.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   the request (supplies url, method,
+ *   headers, logger, and `request.server` for serverUrl + storage)
+ * @param options.allowedTarget {string}   the capability's expected
+ *   invocationTarget (full URL, including host and port)
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @param options.spaceController {IDID}   the did:key that controls the Space
+ * @param [options.requestName] {string}   human-readable request name, used in
+ *   error titles
+ * @param [options.allowTargetQuery] {boolean}   tolerate query parameters that
+ *   extend `allowedTarget` on the capability-invocation path (see `verifyZcap`)
+ * @param [options.attenuatedRootTarget] {string}   ancestor target (the Space
+ *   URL) whose root capability is also accepted as the root of a delegated
+ *   chain attenuating down to the request URL (see `verifyZcap`)
+ * @returns {Promise<void>}   resolves when authorized; throws otherwise
+ */
+export declare function authorize({ request, allowedTarget, spaceId, collectionId, resourceId, spaceController, requestName, allowTargetQuery, attenuatedRootTarget }: {
+    request: FastifyRequest;
+    allowedTarget: string;
+    spaceId: string;
+    collectionId?: string;
+    resourceId?: string;
+    spaceController: IDID;
+    requestName?: string;
+    allowTargetQuery?: boolean;
+    attenuatedRootTarget?: string;
+}): Promise<void>;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAQ7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,EAC9B,OAAO,EACP,aAAa,EACb,OAAO,EACP,YAAY,EACZ,UAAU,EACV,eAAe,EACf,WAAgB,EAChB,gBAAwB,EACxB,oBAAoB,EACrB,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDhB"}

package/dist/authorize.js

@@ -0,0 +1,76 @@
+import { handleZcapVerify } from './zcap.js';
+import { resolveEffectivePolicy, policyGrants } from './policy.js';
+import { UnauthorizedError } from './errors.js';
+/**
+ * Authorizes a request against a target, by capability invocation first and the
+ * effective access-control policy second.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   the request (supplies url, method,
+ *   headers, logger, and `request.server` for serverUrl + storage)
+ * @param options.allowedTarget {string}   the capability's expected
+ *   invocationTarget (full URL, including host and port)
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @param options.spaceController {IDID}   the did:key that controls the Space
+ * @param [options.requestName] {string}   human-readable request name, used in
+ *   error titles
+ * @param [options.allowTargetQuery] {boolean}   tolerate query parameters that
+ *   extend `allowedTarget` on the capability-invocation path (see `verifyZcap`)
+ * @param [options.attenuatedRootTarget] {string}   ancestor target (the Space
+ *   URL) whose root capability is also accepted as the root of a delegated
+ *   chain attenuating down to the request URL (see `verifyZcap`)
+ * @returns {Promise<void>}   resolves when authorized; throws otherwise
+ */
+export async function authorize({ request, allowedTarget, spaceId, collectionId, resourceId, spaceController, requestName = '', allowTargetQuery = false, attenuatedRootTarget }) {
+    const { url, method, headers } = request;
+    const { serverUrl, storage } = request.server;
+    const action = method === 'GET' || method === 'HEAD' ? 'read' : 'write';
+    // 1. If the caller presented a capability invocation, try it first. Success
+    // authorizes the request; failure -- a revoked capability included -- falls
+    // through to the policy check (we hold the error to re-throw if the policy
+    // does not grant access either). Revoking a capability therefore withdraws
+    // only what the capability granted: access a policy already grants everyone
+    // (a public-readable Space) survives, which is the permissive-policy model.
+    let zcapError;
+    if (headers.authorization && headers['capability-invocation']) {
+        try {
+            await handleZcapVerify({
+                url,
+                allowedTarget,
+                allowedAction: method,
+                method,
+                headers,
+                serverUrl,
+                spaceController,
+                requestName,
+                logger: request.log,
+                allowTargetQuery,
+                attenuatedRootTarget,
+                revocation: { storage, scope: { spaceId } }
+            });
+            return;
+        }
+        catch (err) {
+            zcapError = err;
+        }
+    }
+    // 2. Fall back to the target's effective access-control policy.
+    const policy = await resolveEffectivePolicy({
+        storage,
+        spaceId,
+        collectionId,
+        resourceId
+    });
+    if (policyGrants({ policy, action, logger: request.log })) {
+        // Log granted public-access decisions so they are auditable (an anonymous
+        // or otherwise-unauthorized read allowed purely by a policy).
+        request.log.info({ spaceId, collectionId, resourceId, action, policyType: policy?.type }, 'Access granted by access-control policy.');
+        return;
+    }
+    // Neither a capability nor a policy authorizes this request. Re-throw the
+    // capability error when there was one, else a generic 404 (no leak).
+    throw zcapError ?? new UnauthorizedError({ requestName });
+}
+//# sourceMappingURL=authorize.js.map

package/dist/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EACL,sBAAsB,EACtB,YAAY,EAEb,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAC9B,OAAO,EACP,aAAa,EACb,OAAO,EACP,YAAY,EACZ,UAAU,EACV,eAAe,EACf,WAAW,GAAG,EAAE,EAChB,gBAAgB,GAAG,KAAK,EACxB,oBAAoB,EAWrB;IACC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IACxC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAA;IAC7C,MAAM,MAAM,GACV,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAA;IAE1D,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,4EAA4E;IAC5E,IAAI,SAA4B,CAAA;IAChC,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,uBAAuB,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,gBAAgB,CAAC;gBACrB,GAAG;gBACH,aAAa;gBACb,aAAa,EAAE,MAAM;gBACrB,MAAM;gBACN,OAAO;gBACP,SAAS;gBACT,eAAe;gBACf,WAAW;gBACX,MAAM,EAAE,OAAO,CAAC,GAAG;gBACnB,gBAAgB;gBAChB,oBAAoB;gBACpB,UAAU,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE;aAC5C,CAAC,CAAA;YACF,OAAM;QACR,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAY,CAAA;QAC1B,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC;QAC1C,OAAO;QACP,OAAO;QACP,YAAY;QACZ,UAAU;KACX,CAAC,CAAA;IACF,IAAI,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC1D,0EAA0E;QAC1E,8DAA8D;QAC9D,OAAO,CAAC,GAAG,CAAC,IAAI,CACd,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,EACvE,0CAA0C,CAC3C,CAAA;QACD,OAAM;IACR,CAAC;IAED,0EAA0E;IAC1E,qEAAqE;IACrE,MAAM,SAAS,IAAI,IAAI,iBAAiB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAA;AAC3D,CAAC"}