was-teaching-server 0.9.1

package/dist/lib/paths.js

@@ -0,0 +1,270 @@
+/**
+ * Single source of truth for the server's relative URL path templates. The route
+ * shapes registered in `routes.ts` (the `/spaces` repository, `/space/:spaceId`,
+ * `/space/:spaceId/:collectionId`, the `policy` / `linkset` auxiliary resources,
+ * and the `export` / `import` actions) are mirrored here as builder functions, so
+ * handlers, the policy code, and the storage backends construct the same paths
+ * from one place rather than re-deriving them inline (which risks drift from the
+ * routes).
+ *
+ * Builders return the canonical, no-trailing-slash member form by default. The
+ * spec assigns distinct meaning to a trailing slash -- it addresses the
+ * container / "list-or-add-to" view of a member -- so the container builders take
+ * an explicit `trailingSlash` option (or, for the always-container `/spaces/` and
+ * `.../collections/`, bake the slash in) rather than leaving the slash to drift
+ * across call sites. A leaf Resource has no children, so `resourcePath` has no
+ * container form.
+ */
+/**
+ * The SpacesRepository container (`/spaces/`) or one of its members
+ * (`/spaces/:spaceId`). The member form is used for the `Location` header of a
+ * newly created Space; the container form is the `POST`/`GET` target.
+ * @param options {object}
+ * @param [options.spaceId] {string}   when present, the repository member path;
+ *   otherwise the (trailing-slash) container path
+ * @returns {string}
+ */
+export function spacesPath({ spaceId } = {}) {
+    return spaceId !== undefined ? `/spaces/${spaceId}` : `/spaces/`;
+}
+/**
+ * `/space/:spaceId` (member) or `/space/:spaceId/` (container -- the
+ * "add a Collection" / Space-as-container view) when `trailingSlash` is set.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param [options.trailingSlash] {boolean}   address the container form
+ * @returns {string}
+ */
+export function spacePath({ spaceId, trailingSlash = false }) {
+    return `/space/${spaceId}${trailingSlash ? '/' : ''}`;
+}
+/**
+ * `/space/:spaceId/collections/` -- the "List Collections" container path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function collectionsPath({ spaceId }) {
+    return `${spacePath({ spaceId })}/collections/`;
+}
+/**
+ * `/space/:spaceId/export` -- the "Export Space" action path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function exportPath({ spaceId }) {
+    return `${spacePath({ spaceId })}/export`;
+}
+/**
+ * `/space/:spaceId/import` -- the "Import Space" action path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function importPath({ spaceId }) {
+    return `${spacePath({ spaceId })}/import`;
+}
+/**
+ * `/space/:spaceId/:collectionId` (member) or `/space/:spaceId/:collectionId/`
+ * (container -- the "add a Resource" / "list items" view) when `trailingSlash`
+ * is set.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param [options.trailingSlash] {boolean}   address the container form
+ * @returns {string}
+ */
+export function collectionPath({ spaceId, collectionId, trailingSlash = false }) {
+    return `/space/${spaceId}/${collectionId}${trailingSlash ? '/' : ''}`;
+}
+/**
+ * `/space/:spaceId/:collectionId/:resourceId`
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {string}
+ */
+export function resourcePath({ spaceId, collectionId, resourceId }) {
+    return `/space/${spaceId}/${collectionId}/${resourceId}`;
+}
+/**
+ * The `policy` auxiliary resource path for whichever level the ids address:
+ * Space (`spaceId`), Collection (`+ collectionId`), or Resource
+ * (`+ collectionId + resourceId`).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @returns {string}
+ */
+export function policyPath({ spaceId, collectionId, resourceId }) {
+    if (collectionId !== undefined && resourceId !== undefined) {
+        return `${resourcePath({ spaceId, collectionId, resourceId })}/policy`;
+    }
+    if (collectionId !== undefined) {
+        return `${collectionPath({ spaceId, collectionId })}/policy`;
+    }
+    return `${spacePath({ spaceId })}/policy`;
+}
+/**
+ * `/space/:spaceId/backends` -- the "Space Backends Available" list path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function backendsPath({ spaceId }) {
+    return `${spacePath({ spaceId })}/backends`;
+}
+/**
+ * `/space/:spaceId/backends/:backendId` -- a single registered `external`
+ * backend record (the `POST` `Location` target, and the `PUT`/`DELETE` member
+ * path). Distinct from {@link backendPath}, which is a Collection's *selected*
+ * backend resource.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.backendId {string}
+ * @returns {string}
+ */
+export function registeredBackendPath({ spaceId, backendId }) {
+    return `${backendsPath({ spaceId })}/${backendId}`;
+}
+/**
+ * `/space/:spaceId/quotas` -- the Space Quota report path (spec "Quotas").
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function quotasPath({ spaceId }) {
+    return `${spacePath({ spaceId })}/quotas`;
+}
+/**
+ * `/space/:spaceId/:collectionId/:resourceId/meta` -- the Resource Metadata
+ * (reserved `meta` segment) path. Reserved only at the Resource level, so it
+ * takes the full id triple.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {string}
+ */
+export function metaPath({ spaceId, collectionId, resourceId }) {
+    return `${resourcePath({ spaceId, collectionId, resourceId })}/meta`;
+}
+/**
+ * `/space/:spaceId/:collectionId/backend` -- the "Collection Backend Selected"
+ * resource path (reserved `backend` segment at the Resource level).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @returns {string}
+ */
+export function backendPath({ spaceId, collectionId }) {
+    return `${collectionPath({ spaceId, collectionId })}/backend`;
+}
+/**
+ * `/space/:spaceId/:collectionId/quota` -- the per-Collection storage quota
+ * report path (reserved `quota` segment at the Resource level; spec "Quotas").
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @returns {string}
+ */
+export function quotaPath({ spaceId, collectionId }) {
+    return `${collectionPath({ spaceId, collectionId })}/quota`;
+}
+/**
+ * `/space/:spaceId/:collectionId/query` -- the reserved `query` endpoint for a
+ * Collection (spec "Collection-level reserved endpoints"). The WAS server serves
+ * the replication change feed as the `changes` profile of this endpoint.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @returns {string}
+ */
+export function queryPath({ spaceId, collectionId }) {
+    return `${collectionPath({ spaceId, collectionId })}/query`;
+}
+/**
+ * The `linkset` discovery resource path for a Space (`spaceId`) or Collection
+ * (`+ collectionId`).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @returns {string}
+ */
+export function linksetPath({ spaceId, collectionId }) {
+    const anchor = collectionId !== undefined
+        ? collectionPath({ spaceId, collectionId })
+        : spacePath({ spaceId });
+    return `${anchor}/linkset`;
+}
+/**
+ * `/kms/keystores` -- the WebKMS keystores collection (create/list target; the
+ * `/kms` facet) or one of its member keystores
+ * (`/kms/keystores/:keystoreId`). Unlike the WAS builders there is no
+ * trailing-slash container form: the webkms protocol
+ * (`@interop/webkms-client`) posts to the bare collection path.
+ * @param options {object}
+ * @param [options.keystoreId] {string}   the keystore's server-generated local
+ *   id; when present, the member path, otherwise the collection path
+ * @returns {string}
+ */
+export function kmsKeystoresPath({ keystoreId } = {}) {
+    return keystoreId !== undefined
+        ? `/kms/keystores/${keystoreId}`
+        : '/kms/keystores';
+}
+/**
+ * `/kms/keystores/:keystoreId/keys` -- a keystore's keys collection (the
+ * `GenerateKeyOperation` target) or one of its member keys
+ * (`/kms/keystores/:keystoreId/keys/:keyId`, the key-operation / description
+ * target). Like `kmsKeystoresPath`, no trailing-slash form exists: the webkms
+ * protocol's URLs are exact.
+ * @param options {object}
+ * @param options.keystoreId {string}   the keystore's local id
+ * @param [options.keyId] {string}   the key's server-generated local id; when
+ *   present, the member path, otherwise the collection path
+ * @returns {string}
+ */
+export function kmsKeysPath({ keystoreId, keyId }) {
+    const keysPath = `${kmsKeystoresPath({ keystoreId })}/keys`;
+    return keyId !== undefined ? `${keysPath}/${keyId}` : keysPath;
+}
+/**
+ * `/kms/keystores/:keystoreId/zcaps/revocations/:revocationId` -- a keystore's
+ * zcap revocation submission target (POST; the ezcap-express
+ * `/zcaps/revocations/` convention). `revocationId` is the *to-be-revoked
+ * capability's id*, URL-encoded into the single path segment the route
+ * expects -- the same `encodeURIComponent` framing `@interop/webkms-client`'s
+ * `revokeCapability` puts on the wire.
+ * @param options {object}
+ * @param options.keystoreId {string}   the keystore's local id
+ * @param options.revocationId {string}   the to-be-revoked capability's id
+ *   (raw, un-encoded)
+ * @returns {string}
+ */
+export function kmsRevocationsPath({ keystoreId, revocationId }) {
+    return (`${kmsKeystoresPath({ keystoreId })}/zcaps/revocations/` +
+        encodeURIComponent(revocationId));
+}
+/**
+ * `/space/:spaceId/zcaps/revocations/:revocationId` -- a Space's zcap
+ * revocation submission target (POST), the WAS-route sibling of
+ * `kmsRevocationsPath` and the same ezcap-express `/zcaps/revocations/`
+ * convention. `revocationId` is the *to-be-revoked capability's id*,
+ * URL-encoded into the single path segment the route expects. The `zcaps`
+ * segment sits four levels under `/space`, deeper than any Collection or
+ * Resource route, so it shadows neither and needs no reserved-id entry.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.revocationId {string}   the to-be-revoked capability's id
+ *   (raw, un-encoded)
+ * @returns {string}
+ */
+export function spaceRevocationsPath({ spaceId, revocationId }) {
+    return (`${spacePath({ spaceId })}/zcaps/revocations/` +
+        encodeURIComponent(revocationId));
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/paths.js.map

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

package/dist/lib/preconditions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Evaluates a content-write (or delete) precondition against a Resource's
+ * current state. Throws `PreconditionFailedError` (412) when it is not met.
+ * `ifNoneMatch` (`If-None-Match: *`, create-if-absent) takes precedence over
+ * `ifMatch` when both are present (RFC9110): the write proceeds only if the
+ * Resource is absent. `ifMatch` (update-if-unchanged) requires the Resource to
+ * exist with a current ETag equal to the supplied validator.
+ * @param options {object}
+ * @param options.resourceId {string}   for the error detail
+ * @param options.exists {boolean}   whether the Resource currently exists (a
+ *   tombstone counts as "does not exist")
+ * @param options.currentVersion {number}   the Resource's current content
+ *   `version` (0 for a legacy Resource without one)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` (create-if-absent)
+ * @returns {void}
+ */
+export declare function assertWritePrecondition({ resourceId, exists, currentVersion, ifMatch, ifNoneMatch }: {
+    resourceId: string;
+    exists: boolean;
+    currentVersion: number;
+    ifMatch?: string;
+    ifNoneMatch?: boolean;
+}): void;
+/**
+ * Evaluates a Collection Description write precondition against the Collection's
+ * current description `version` (the `key-epochs` / conditional-Collection-write
+ * feature). Throws `PreconditionFailedError` (412) when the supplied `If-Match`
+ * validator does not equal the current description ETag. Only `If-Match`
+ * (update-if-unchanged) is supported for Collections; a create through an
+ * unconditional PUT is unaffected. MUST be called atomically with the write
+ * (under the filesystem backend's per-Collection lock, or inside the Postgres
+ * backend's row-locking transaction).
+ * @param options {object}
+ * @param options.collectionId {string}   for the error detail
+ * @param options.currentVersion {number}   the Collection's current description
+ *   `version` (0 for a legacy Collection without one, or before its first write)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @returns {void}
+ */
+export declare function assertCollectionWritePrecondition({ collectionId, currentVersion, ifMatch }: {
+    collectionId: string;
+    currentVersion: number;
+    ifMatch?: string;
+}): void;
+/**
+ * Evaluates a metadata-write (`/meta`) precondition against a Resource's
+ * current `metaVersion`. Throws `PreconditionFailedError` (412) when it is not
+ * met. `If-None-Match: *` means "only if no metadata has been written yet"
+ * (`metaVersion` unset); `If-Match` pins the current `metaVersion` ETag.
+ * @param options {object}
+ * @param options.resourceId {string}   for the error detail
+ * @param [options.metaVersion] {number}   the current `metaVersion`
+ *   (`undefined` until the first metadata write)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *`
+ * @returns {void}
+ */
+export declare function assertMetaWritePrecondition({ resourceId, metaVersion, ifMatch, ifNoneMatch }: {
+    resourceId: string;
+    metaVersion?: number;
+    ifMatch?: string;
+    ifNoneMatch?: boolean;
+}): void;
+//# sourceMappingURL=preconditions.d.ts.map

package/dist/lib/preconditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preconditions.d.ts","sourceRoot":"","sources":["../../src/lib/preconditions.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,UAAU,EACV,MAAM,EACN,cAAc,EACd,OAAO,EACP,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,OAAO,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,GAAG,IAAI,CA2BP;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iCAAiC,CAAC,EAChD,YAAY,EACZ,cAAc,EACd,OAAO,EACR,EAAE;IACD,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,IAAI,CAUP;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,UAAU,EACV,WAAW,EACX,OAAO,EACP,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,GAAG,IAAI,CAeP"}

package/dist/lib/preconditions.js

@@ -0,0 +1,112 @@
+/**
+ * Backend-agnostic conditional-write precondition evaluation (the
+ * `conditional-writes` feature). Both storage backends evaluate `If-Match` /
+ * `If-None-Match` against a Resource's current state through these two
+ * helpers, so the 412 semantics cannot drift between them. Callers MUST invoke
+ * them atomically with the write that follows (under the filesystem backend's
+ * per-Resource lock, or inside the Postgres backend's row-locking
+ * transaction).
+ */
+import { PreconditionFailedError } from '../errors.js';
+import { formatEtag } from './etag.js';
+/**
+ * Evaluates a content-write (or delete) precondition against a Resource's
+ * current state. Throws `PreconditionFailedError` (412) when it is not met.
+ * `ifNoneMatch` (`If-None-Match: *`, create-if-absent) takes precedence over
+ * `ifMatch` when both are present (RFC9110): the write proceeds only if the
+ * Resource is absent. `ifMatch` (update-if-unchanged) requires the Resource to
+ * exist with a current ETag equal to the supplied validator.
+ * @param options {object}
+ * @param options.resourceId {string}   for the error detail
+ * @param options.exists {boolean}   whether the Resource currently exists (a
+ *   tombstone counts as "does not exist")
+ * @param options.currentVersion {number}   the Resource's current content
+ *   `version` (0 for a legacy Resource without one)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` (create-if-absent)
+ * @returns {void}
+ */
+export function assertWritePrecondition({ resourceId, exists, currentVersion, ifMatch, ifNoneMatch }) {
+    if (ifNoneMatch) {
+        if (exists) {
+            throw new PreconditionFailedError({
+                detail: `Resource '${resourceId}' already exists (If-None-Match: *).`
+            });
+        }
+        return;
+    }
+    if (ifMatch === undefined) {
+        return;
+    }
+    // `If-Match` (update-if-unchanged): the Resource must exist and its current
+    // ETag must equal the supplied validator.
+    if (!exists) {
+        throw new PreconditionFailedError({
+            detail: `Resource '${resourceId}' does not exist; If-Match cannot be satisfied.`
+        });
+    }
+    const currentEtag = formatEtag(currentVersion);
+    if (currentEtag !== ifMatch) {
+        throw new PreconditionFailedError({
+            detail: `Resource '${resourceId}' ETag ${currentEtag} does not match If-Match ${ifMatch}.`
+        });
+    }
+}
+/**
+ * Evaluates a Collection Description write precondition against the Collection's
+ * current description `version` (the `key-epochs` / conditional-Collection-write
+ * feature). Throws `PreconditionFailedError` (412) when the supplied `If-Match`
+ * validator does not equal the current description ETag. Only `If-Match`
+ * (update-if-unchanged) is supported for Collections; a create through an
+ * unconditional PUT is unaffected. MUST be called atomically with the write
+ * (under the filesystem backend's per-Collection lock, or inside the Postgres
+ * backend's row-locking transaction).
+ * @param options {object}
+ * @param options.collectionId {string}   for the error detail
+ * @param options.currentVersion {number}   the Collection's current description
+ *   `version` (0 for a legacy Collection without one, or before its first write)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @returns {void}
+ */
+export function assertCollectionWritePrecondition({ collectionId, currentVersion, ifMatch }) {
+    if (ifMatch === undefined) {
+        return;
+    }
+    const currentEtag = formatEtag(currentVersion);
+    if (currentEtag !== ifMatch) {
+        throw new PreconditionFailedError({
+            detail: `Collection '${collectionId}' ETag ${currentEtag} does not match If-Match ${ifMatch}.`
+        });
+    }
+}
+/**
+ * Evaluates a metadata-write (`/meta`) precondition against a Resource's
+ * current `metaVersion`. Throws `PreconditionFailedError` (412) when it is not
+ * met. `If-None-Match: *` means "only if no metadata has been written yet"
+ * (`metaVersion` unset); `If-Match` pins the current `metaVersion` ETag.
+ * @param options {object}
+ * @param options.resourceId {string}   for the error detail
+ * @param [options.metaVersion] {number}   the current `metaVersion`
+ *   (`undefined` until the first metadata write)
+ * @param [options.ifMatch] {string}   a quoted ETag (`If-Match`)
+ * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *`
+ * @returns {void}
+ */
+export function assertMetaWritePrecondition({ resourceId, metaVersion, ifMatch, ifNoneMatch }) {
+    if (ifNoneMatch) {
+        if (metaVersion !== undefined) {
+            throw new PreconditionFailedError({
+                detail: `Resource '${resourceId}' metadata already exists (If-None-Match: *).`
+            });
+        }
+    }
+    else if (ifMatch !== undefined) {
+        const currentEtag = formatEtag(metaVersion ?? 0);
+        if (currentEtag !== ifMatch) {
+            throw new PreconditionFailedError({
+                detail: `Resource '${resourceId}' metadata ETag ${currentEtag} does not match If-Match ${ifMatch}.`
+            });
+        }
+    }
+}
+//# sourceMappingURL=preconditions.js.map

package/dist/lib/preconditions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preconditions.js","sourceRoot":"","sources":["../../src/lib/preconditions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACtC,UAAU,EACV,MAAM,EACN,cAAc,EACd,OAAO,EACP,WAAW,EAOZ;IACC,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,IAAI,uBAAuB,CAAC;gBAChC,MAAM,EAAE,aAAa,UAAU,sCAAsC;aACtE,CAAC,CAAA;QACJ,CAAC;QACD,OAAM;IACR,CAAC;IAED,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAM;IACR,CAAC;IAED,4EAA4E;IAC5E,0CAA0C;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,uBAAuB,CAAC;YAChC,MAAM,EAAE,aAAa,UAAU,iDAAiD;SACjF,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,UAAU,CAAC,cAAc,CAAC,CAAA;IAC9C,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,uBAAuB,CAAC;YAChC,MAAM,EAAE,aAAa,UAAU,UAAU,WAAW,4BAA4B,OAAO,GAAG;SAC3F,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iCAAiC,CAAC,EAChD,YAAY,EACZ,cAAc,EACd,OAAO,EAKR;IACC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAM;IACR,CAAC;IACD,MAAM,WAAW,GAAG,UAAU,CAAC,cAAc,CAAC,CAAA;IAC9C,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,uBAAuB,CAAC;YAChC,MAAM,EAAE,eAAe,YAAY,UAAU,WAAW,4BAA4B,OAAO,GAAG;SAC/F,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAC1C,UAAU,EACV,WAAW,EACX,OAAO,EACP,WAAW,EAMZ;IACC,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,uBAAuB,CAAC;gBAChC,MAAM,EAAE,aAAa,UAAU,+CAA+C;aAC/E,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,IAAI,CAAC,CAAC,CAAA;QAChD,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,uBAAuB,CAAC;gBAChC,MAAM,EAAE,aAAa,UAAU,mBAAmB,WAAW,4BAA4B,OAAO,GAAG;aACpG,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/lib/resourceFileName.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Percent-encodes a filename segment so it carries no literal `.`, the
+ * structural delimiter of `r.<resourceId>.<encodedContentType>.<ext>`.
+ * `encodeURIComponent` leaves `.` unescaped, so escape it explicitly to `%2E`;
+ * `decodeURIComponent` reverses both. This keeps resource ids and content-types
+ * that legitimately contain dots (e.g. `index.html`, `application/vnd.api+json`)
+ * unambiguously parseable -- without it, a dotted id mis-splits and is read back
+ * under the wrong id and content-type. For dot-free segments (the common case)
+ * the result is byte-identical to the previous `encodeURIComponent`-only scheme.
+ * @param segment {string}
+ * @returns {string}
+ */
+export declare function encodeFilenameSegment(segment: string): string;
+/**
+ * Builds the on-disk filename for a resource representation:
+ * `r.<resourceId>.<encodedContentType>.<ext>`. Both the `resourceId` and
+ * content-type segments are dot-escaped (see {@link encodeFilenameSegment}) so
+ * the three `.` separators are the only literal dots.
+ * @param options {object}
+ * @param options.resourceId {string}
+ * @param options.contentType {string}
+ * @returns {string}
+ */
+export declare function fileNameFor({ resourceId, contentType }: {
+    resourceId: string;
+    contentType: string;
+}): string;
+/**
+ * Parses an on-disk resource filename (`r.<resourceId>.<encodedContentType>.<ext>`)
+ * back into its components, reversing the dot-escaping {@link fileNameFor}
+ * applies. Returns the exact stored content-type (decoded from the filename
+ * segment, more reliable than `mime.lookup` on the extension), falling back to
+ * the spec default `application/octet-stream` if unparseable.
+ * @param fileName {string}   the basename of the resource file
+ * @returns {{ resourceId: string, contentType: string }}
+ */
+export declare function parseResourceFileName(fileName: string): {
+    resourceId: string;
+    contentType: string;
+};
+//# sourceMappingURL=resourceFileName.d.ts.map

package/dist/lib/resourceFileName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceFileName.d.ts","sourceRoot":"","sources":["../../src/lib/resourceFileName.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,UAAU,EACV,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB,GAAG,MAAM,CAKT;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB,CAQA"}

package/dist/lib/resourceFileName.js

@@ -0,0 +1,58 @@
+/**
+ * On-disk resource-filename codec: the single shared home for encoding a
+ * Resource's representation file name (`r.<resourceId>.<encodedContentType>.<ext>`)
+ * and decoding it back. Kept low-level (no imports from `src/backends/` or
+ * `importTar.ts`) so both the filesystem backend and the tar importer can depend
+ * on it without an import cycle.
+ */
+import * as mime from 'mime-types';
+/**
+ * Percent-encodes a filename segment so it carries no literal `.`, the
+ * structural delimiter of `r.<resourceId>.<encodedContentType>.<ext>`.
+ * `encodeURIComponent` leaves `.` unescaped, so escape it explicitly to `%2E`;
+ * `decodeURIComponent` reverses both. This keeps resource ids and content-types
+ * that legitimately contain dots (e.g. `index.html`, `application/vnd.api+json`)
+ * unambiguously parseable -- without it, a dotted id mis-splits and is read back
+ * under the wrong id and content-type. For dot-free segments (the common case)
+ * the result is byte-identical to the previous `encodeURIComponent`-only scheme.
+ * @param segment {string}
+ * @returns {string}
+ */
+export function encodeFilenameSegment(segment) {
+    return encodeURIComponent(segment).replace(/\./g, '%2E');
+}
+/**
+ * Builds the on-disk filename for a resource representation:
+ * `r.<resourceId>.<encodedContentType>.<ext>`. Both the `resourceId` and
+ * content-type segments are dot-escaped (see {@link encodeFilenameSegment}) so
+ * the three `.` separators are the only literal dots.
+ * @param options {object}
+ * @param options.resourceId {string}
+ * @param options.contentType {string}
+ * @returns {string}
+ */
+export function fileNameFor({ resourceId, contentType }) {
+    const encodedId = encodeFilenameSegment(resourceId);
+    const encodedType = encodeFilenameSegment(contentType);
+    const extension = mime.extension(contentType) || 'blob';
+    return `r.${encodedId}.${encodedType}.${extension}`;
+}
+/**
+ * Parses an on-disk resource filename (`r.<resourceId>.<encodedContentType>.<ext>`)
+ * back into its components, reversing the dot-escaping {@link fileNameFor}
+ * applies. Returns the exact stored content-type (decoded from the filename
+ * segment, more reliable than `mime.lookup` on the extension), falling back to
+ * the spec default `application/octet-stream` if unparseable.
+ * @param fileName {string}   the basename of the resource file
+ * @returns {{ resourceId: string, contentType: string }}
+ */
+export function parseResourceFileName(fileName) {
+    const [, encodedId, encodedType] = fileName.split('.');
+    return {
+        resourceId: encodedId ? decodeURIComponent(encodedId) : '',
+        contentType: encodedType
+            ? decodeURIComponent(encodedType)
+            : 'application/octet-stream'
+    };
+}
+//# sourceMappingURL=resourceFileName.js.map

package/dist/lib/resourceFileName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceFileName.js","sourceRoot":"","sources":["../../src/lib/resourceFileName.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAElC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,UAAU,EACV,WAAW,EAIZ;IACC,MAAM,SAAS,GAAG,qBAAqB,CAAC,UAAU,CAAC,CAAA;IACnD,MAAM,WAAW,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAA;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,MAAM,CAAA;IACvD,OAAO,KAAK,SAAS,IAAI,WAAW,IAAI,SAAS,EAAE,CAAA;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IAIpD,MAAM,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACtD,OAAO;QACL,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE;QAC1D,WAAW,EAAE,WAAW;YACtB,CAAC,CAAC,kBAAkB,CAAC,WAAW,CAAC;YACjC,CAAC,CAAC,0BAA0B;KAC/B,CAAA;AACH,CAAC"}

package/dist/lib/revocations.d.ts

@@ -0,0 +1,49 @@
+import type { CapabilityChainDetails, InspectCapabilityChain } from '@interop/zcap';
+import type { CapabilitySummary, RevocationScope, StorageBackend } from '../types.js';
+/**
+ * The file name a revocation record is stored (and archived) under:
+ * the `(delegator, capabilityId)` unique key folded into a SHA-256 digest,
+ * plus `.json`. Both parts are arbitrary-length URIs, so hashing (rather than
+ * encoding) keeps the name fixed-width and filesystem-safe. Shared by the
+ * filesystem store and both backends' `exportSpace`, so the same record
+ * always lands under the same name.
+ * @param options {object}
+ * @param options.delegator {string}   the revoked capability's delegator
+ * @param options.capabilityId {string}   the revoked capability's id
+ * @returns {string}
+ */
+export declare function revocationFileName({ delegator, capabilityId }: {
+    delegator: string;
+    capabilityId: string;
+}): string;
+/**
+ * Extracts the `(capabilityId, delegator)` lookup pairs from a verified,
+ * dereferenced capability chain. The root capability is skipped -- root zcaps
+ * cannot be revoked -- and so is any link whose verify result carries no
+ * delegator (nothing to key a revocation record on).
+ *
+ * @param options {object}
+ * @param options.capabilityChain {object[]}   the dereferenced chain (root to
+ *   tail)
+ * @param options.capabilityChainMeta {object[]}   the per-capability verify
+ *   results (the root's entry has a `null` `verifyResult`)
+ * @returns {CapabilitySummary[]}
+ */
+export declare function capabilitySummaries({ capabilityChain, capabilityChainMeta }: CapabilityChainDetails): CapabilitySummary[];
+/**
+ * Builds the `inspectCapabilityChain` hook for one scope: valid when no
+ * delegated capability in the chain has a stored revocation under that
+ * keystore or Space (a chain of just the root has nothing to check, so a bare
+ * root invocation never reaches the store).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   supplies the revocation store
+ * @param options.scope {RevocationScope}   the keystore or Space the lookup is
+ *   keyed on
+ * @returns {InspectCapabilityChain}
+ */
+export declare function revocationChainInspector({ storage, scope }: {
+    storage: StorageBackend;
+    scope: RevocationScope;
+}): InspectCapabilityChain;
+//# sourceMappingURL=revocations.d.ts.map

package/dist/lib/revocations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocations.d.ts","sourceRoot":"","sources":["../../src/lib/revocations.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,SAAS,EACT,YAAY,EACb,EAAE;IACD,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,MAAM,CAKT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,eAAe,EACf,mBAAmB,EACpB,EAAE,sBAAsB,GAAG,iBAAiB,EAAE,CAgB9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,KAAK,EACN,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,KAAK,EAAE,eAAe,CAAA;CACvB,GAAG,sBAAsB,CAiBzB"}