@pdsjs/spaces 2.0.1 → 2.0.3

package/src/memory-storage.js

@@ -1,9 +1,54 @@
-// @pdsjs/spaces/memory-storage - in-memory SpaceStoragePort.
+// @pdsjs/spaces/memory-storage - in-memory SpaceStoragePort, and the blob side
+// of the route context.
 //
 // Backs unit tests and gives handler tests a store with no database. Keyed
 // exactly like the SQL adapters so the shared conformance suite exercises the
 // same behaviour everywhere.
 
+/**
+ * The blob store and blob link table createSpaceRoutes wants, in memory. A real
+ * deployment passes the account's own store and link table; here they are two
+ * Maps that answer the same way.
+ *
+ * @returns {{blobs: import('@pdsjs/core/ports').BlobPort, linkBlob: (blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>, unlinkBlobs: (recordUri: string) => Promise<void>, links: Map<string, Set<string>>, put: (cid: string, data: Uint8Array, mimeType?: string) => void}}
+ */
+export function createMemoryBlobContext() {
+  /** @type {Map<string, {data: Uint8Array, mimeType: string}>} */
+  const stored = new Map();
+  /** @type {Map<string, Set<string>>} record uri -> blob cids */
+  const links = new Map();
+
+  return {
+    blobs: {
+      async get(_did, cid) {
+        const blob = stored.get(cid);
+        return blob ? { ...blob, data: new Uint8Array(blob.data) } : null;
+      },
+      async put(_did, cid, data, mimeType) {
+        stored.set(cid, { data: new Uint8Array(data), mimeType });
+      },
+      async delete(_did, cid) {
+        stored.delete(cid);
+      },
+    },
+    async linkBlob(blobCid, recordUri) {
+      let forRecord = links.get(recordUri);
+      if (!forRecord) {
+        forRecord = new Set();
+        links.set(recordUri, forRecord);
+      }
+      forRecord.add(blobCid);
+    },
+    async unlinkBlobs(recordUri) {
+      links.delete(recordUri);
+    },
+    links,
+    put(cid, data, mimeType = 'application/octet-stream') {
+      stored.set(cid, { data, mimeType });
+    },
+  };
+}
+
 /**
  * Keyset pagination over a sorted key list.
  * @template T
@@ -117,17 +162,31 @@ export function createMemorySpaceStorage() {
       return records.get(space)?.get(`${collection}/${rkey}`)?.cid ?? null;
     },
 
-    async listSpaceRecords(space, collection, cursor, limit) {
+    async listSpaceRecords(
+      space,
+      { collection, cursor, limit, reverse, excludeValues },
+    ) {
       const inSpace = records.get(space) ?? new Map();
-      const keys = [...inSpace.values()]
-        .filter((r) => r.collection === collection)
-        .map((r) => r.rkey)
+      let keys = [...inSpace.values()]
+        .filter((r) => !collection || r.collection === collection)
+        .map((r) => `${r.collection}/${r.rkey}`)
         .sort();
-      const { items, cursor: next } = page(keys, cursor, limit, (rkey) => {
-        const row = inSpace.get(`${collection}/${rkey}`);
-        return { ...row, value: new Uint8Array(row.value) };
+      // Descending unless the caller asks otherwise, matching the reference.
+      if (!reverse) keys.reverse();
+      if (cursor) {
+        keys = keys.filter((k) => (reverse ? k > cursor : k < cursor));
+      }
+      const items = keys.slice(0, limit).map((key) => {
+        const row = inSpace.get(key);
+        const { value, ...rest } = row;
+        return excludeValues
+          ? { ...rest }
+          : { ...rest, value: new Uint8Array(value) };
       });
-      return { records: items, cursor: next };
+      return {
+        records: items,
+        cursor: items.length === limit ? keys[limit - 1] : null,
+      };
     },
 
     async listAllSpaceRecords(space) {
@@ -226,19 +285,27 @@ export function createMemorySpaceStorage() {
       space,
       serviceDid,
       serviceEndpoint,
-      lastIssuedAt,
+      expiresAt,
     ) {
       let inSpace = recipients.get(space);
       if (!inSpace) {
         inSpace = new Map();
         recipients.set(space, inSpace);
       }
-      inSpace.set(serviceDid, { serviceDid, serviceEndpoint, lastIssuedAt });
+      inSpace.set(serviceDid, { serviceDid, serviceEndpoint, expiresAt });
+    },
+
+    async deleteCredentialRecipient(space, serviceDid) {
+      recipients.get(space)?.delete(serviceDid);
     },
 
     async listCredentialRecipients(space) {
       const inSpace = recipients.get(space) ?? new Map();
-      return [...inSpace.keys()].sort().map((k) => ({ ...inSpace.get(k) }));
+      const now = new Date().toISOString();
+      return [...inSpace.keys()]
+        .sort()
+        .map((k) => ({ ...inSpace.get(k) }))
+        .filter((r) => r.expiresAt > now);
     },
   };
 }

package/src/notify.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Forward a write notice to every service registered for this space.
+ *
+ * Best effort, and deliberately so: sync correctness rests on comparing set
+ * hashes, so a syncer that misses a notice finds out on the next one or on its
+ * own next walk. One unreachable recipient must not fail the others, and none of
+ * them may fail the write that produced the notice.
+ *
+ * The caller awaits this, which puts one round trip per recipient in front of
+ * the response. A Worker cancels a promise still running when it answers, and
+ * this package holds no execution context to hand the work to, so backgrounding
+ * it here would mean dropping notifications on Cloudflare.
+ *
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
+ * @param {typeof fetch} [ctx.fetch]
+ * @param {Object} notice
+ * @param {string} notice.authorityDid - the space's authority, which signs
+ * @param {string} notice.space
+ * @param {string} notice.repo - the account whose repo advanced
+ * @param {string} notice.rev
+ * @param {Uint8Array} notice.hash - the repo's commit hash after the write
+ * @returns {Promise<void>}
+ */
+export declare function forwardToSyncers(ctx: {
+    spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    getSigner: () => Promise<import('./token.js').SpaceSigner>;
+    fetch?: typeof fetch;
+}, { authorityDid, space, repo, rev, hash }: {
+    authorityDid: string;
+    space: string;
+    repo: string;
+    rev: string;
+    hash: Uint8Array;
+}): Promise<void>;

package/src/notify.js

@@ -0,0 +1,87 @@
+// @pdsjs/spaces/notify - telling a space's syncers that a repo advanced.
+//
+// A space's writes are never broadcast, which is the point of one. So a service
+// that wants to follow a space registers with the authority through
+// registerNotify, and the authority forwards each write notice it learns of. A
+// syncer that receives one holds a session and can read; the notice itself
+// carries no records, only the rev the repo reached.
+
+import { createServiceAuth } from './service-auth.js';
+
+/**
+ * Forward a write notice to every service registered for this space.
+ *
+ * Best effort, and deliberately so: sync correctness rests on comparing set
+ * hashes, so a syncer that misses a notice finds out on the next one or on its
+ * own next walk. One unreachable recipient must not fail the others, and none of
+ * them may fail the write that produced the notice.
+ *
+ * The caller awaits this, which puts one round trip per recipient in front of
+ * the response. A Worker cancels a promise still running when it answers, and
+ * this package holds no execution context to hand the work to, so backgrounding
+ * it here would mean dropping notifications on Cloudflare.
+ *
+ * @param {Object} ctx
+ * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
+ * @param {typeof fetch} [ctx.fetch]
+ * @param {Object} notice
+ * @param {string} notice.authorityDid - the space's authority, which signs
+ * @param {string} notice.space
+ * @param {string} notice.repo - the account whose repo advanced
+ * @param {string} notice.rev
+ * @param {Uint8Array} notice.hash - the repo's commit hash after the write
+ * @returns {Promise<void>}
+ */
+export async function forwardToSyncers(
+  ctx,
+  { authorityDid, space, repo, rev, hash },
+) {
+  let recipients;
+  try {
+    recipients = await ctx.spaceStorage.listCredentialRecipients(space);
+  } catch {
+    return;
+  }
+  if (recipients.length === 0) return;
+
+  const body = JSON.stringify({ space, repo, rev, hash: toJsonBytes(hash) });
+  const doFetch = ctx.fetch ?? fetch;
+  const signer = await ctx.getSigner();
+
+  await Promise.all(
+    recipients.map(async (recipient) => {
+      try {
+        const token = await createServiceAuth({
+          iss: authorityDid,
+          aud: recipient.serviceDid,
+          lxm: 'com.atproto.space.notifyWrite',
+          signer,
+        });
+        await doFetch(
+          `${recipient.serviceEndpoint}/xrpc/com.atproto.space.notifyWrite`,
+          {
+            method: 'POST',
+            headers: {
+              'content-type': 'application/json',
+              authorization: `Bearer ${token}`,
+            },
+            body,
+          },
+        );
+      } catch {
+        // Best effort.
+      }
+    }),
+  );
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {{$bytes: string}}
+ */
+function toJsonBytes(bytes) {
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return { $bytes: btoa(binary).replace(/=+$/, '') };
+}

package/src/routes.d.ts

@@ -1,23 +1,31 @@
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {import('@pdsjs/core/ports').BlobPort} ctx.blobs - blobs referenced
+ *   from space records live in the account's ordinary blob store
+ * @param {(blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>} ctx.linkBlob
+ * @param {(recordUri: string) => Promise<void>} ctx.unlinkBlobs
  * @param {() => Promise<string|null>} ctx.getDid - the hosted account's DID
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
  *   - the account's signing key, used to sign repo commits and space tokens
- * @param {(did: string) => Promise<any>} ctx.resolveDid - DID document lookup,
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid - DID document lookup,
  *   injected so this package stays dependency-free
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {import('@pdsjs/core/ports').RecordWriteGuardPort} [ctx.recordGuard]
+ *   - a veto over writes in its named collections, e.g. git branch protection
  * @param {typeof fetch} [ctx.fetch] - injected for the outbound notification
  *   calls, so tests can observe them without a network
  * @returns {import('@pdsjs/core/pds').Routes}
  */
 export declare function createSpaceRoutes(ctx: {
     spaceStorage: import('@pdsjs/core/ports').SpaceStoragePort;
+    blobs: import('@pdsjs/core/ports').BlobPort;
+    linkBlob: (blobCid: string, recordUri: string, recordTime: number | null) => Promise<void>;
+    unlinkBlobs: (recordUri: string) => Promise<void>;
     getDid: () => Promise<string | null>;
-    getSigner: () => Promise<{
-        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-    }>;
-    resolveDid: (did: string) => Promise<any>;
+    getSigner: () => Promise<import('./token.js').SpaceSigner>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
+    recordGuard?: import('@pdsjs/core/ports').RecordWriteGuardPort;
     fetch?: typeof fetch;
 }): import('@pdsjs/core/pds').Routes;

package/src/routes.js

@@ -13,12 +13,18 @@ import { createWriteRoutes } from './handlers/write.js';
 /**
  * @param {Object} ctx
  * @param {import('@pdsjs/core/ports').SpaceStoragePort} ctx.spaceStorage
+ * @param {import('@pdsjs/core/ports').BlobPort} ctx.blobs - blobs referenced
+ *   from space records live in the account's ordinary blob store
+ * @param {(blobCid: string, recordUri: string, recordTime: number|null) => Promise<void>} ctx.linkBlob
+ * @param {(recordUri: string) => Promise<void>} ctx.unlinkBlobs
  * @param {() => Promise<string|null>} ctx.getDid - the hosted account's DID
- * @param {() => Promise<{sign: (bytes: Uint8Array) => Promise<Uint8Array>}>} ctx.getSigner
+ * @param {() => Promise<import('./token.js').SpaceSigner>} ctx.getSigner
  *   - the account's signing key, used to sign repo commits and space tokens
- * @param {(did: string) => Promise<any>} ctx.resolveDid - DID document lookup,
+ * @param {import('@pdsjs/core/ports').DidResolverPort} ctx.resolveDid - DID document lookup,
  *   injected so this package stays dependency-free
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} ctx.verifier
+ * @param {import('@pdsjs/core/ports').RecordWriteGuardPort} [ctx.recordGuard]
+ *   - a veto over writes in its named collections, e.g. git branch protection
  * @param {typeof fetch} [ctx.fetch] - injected for the outbound notification
  *   calls, so tests can observe them without a network
  * @returns {import('@pdsjs/core/pds').Routes}
@@ -33,6 +39,13 @@ export function createSpaceRoutes(ctx) {
   if (!ctx.resolveDid || !ctx.verifier) {
     throw new Error('createSpaceRoutes requires resolveDid and a verifier');
   }
+  // Refused rather than defaulted: without the link callbacks a space record's
+  // blobs look unreferenced, and orphan cleanup deletes them.
+  if (!ctx.blobs || !ctx.linkBlob || !ctx.unlinkBlobs) {
+    throw new Error(
+      'createSpaceRoutes requires blobs, linkBlob and unlinkBlobs',
+    );
+  }
   return {
     ...createWriteRoutes(ctx),
     ...createReadRoutes(ctx),

package/src/service-auth.d.ts

@@ -5,7 +5,7 @@
  * @param {string} opts.jwt
  * @param {string} opts.aud - our own DID; the token must be addressed to us
  * @param {string} opts.lxm - the method being called
- * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {import('@pdsjs/core/ports').DidResolverPort} opts.resolveDid
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
  * @returns {Promise<{iss: string}>}
  */
@@ -13,7 +13,7 @@ export declare function verifyServiceAuth({ jwt, aud, lxm, resolveDid, verifier,
     jwt: string;
     aud: string;
     lxm: string;
-    resolveDid: (did: string) => Promise<any>;
+    resolveDid: import('@pdsjs/core/ports').DidResolverPort;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
 }): Promise<{
     iss: string;
@@ -29,14 +29,12 @@ export declare function verifyServiceAuth({ jwt, aud, lxm, resolveDid, verifier,
  * @param {string} opts.iss - our DID
  * @param {string} opts.aud - the service we are calling
  * @param {string} opts.lxm - the method, so the token cannot be replayed elsewhere
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @param {import('./token.js').SpaceSigner} opts.signer
  * @returns {Promise<string>}
  */
 export declare function createServiceAuth({ iss, aud, lxm, signer }: {
     iss: string;
     aud: string;
     lxm: string;
-    signer: {
-        sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-    };
+    signer: import('./token.js').SpaceSigner;
 }): Promise<string>;

package/src/service-auth.js

@@ -7,7 +7,7 @@
 
 import { base64UrlEncode, bytesToHex } from '@pdsjs/core/crypto';
 import { atprotoSigningKey } from './authority.js';
-import { SpaceTokenError } from './token.js';
+import { assertKeyAlg, SpaceTokenError, signerAlg } from './token.js';
 
 const CLOCK_SKEW_SEC = 5;
 
@@ -43,7 +43,7 @@ function decodeSig(b64) {
  * @param {string} opts.jwt
  * @param {string} opts.aud - our own DID; the token must be addressed to us
  * @param {string} opts.lxm - the method being called
- * @param {(did: string) => Promise<any>} opts.resolveDid
+ * @param {import('@pdsjs/core/ports').DidResolverPort} opts.resolveDid
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
  * @returns {Promise<{iss: string}>}
  */
@@ -60,14 +60,19 @@ export async function verifyServiceAuth({
   }
   const [headerB64, payloadB64, sigB64] = parts;
 
+  /** @type {any} */
+  let header;
   /** @type {any} */
   let payload;
   try {
-    decodePart(headerB64);
+    header = decodePart(headerB64);
     payload = decodePart(payloadB64);
   } catch {
     throw new SpaceTokenError('could not parse service token', 'BadJwt');
   }
+  if (typeof header?.alg !== 'string' || !header.alg) {
+    throw new SpaceTokenError('missing service token "alg"', 'BadJwt');
+  }
 
   const now = Math.floor(Date.now() / 1000);
   if (typeof payload.exp !== 'number' || now - CLOCK_SKEW_SEC >= payload.exp) {
@@ -91,30 +96,47 @@ export async function verifyServiceAuth({
     );
   }
 
-  const didDoc = await resolveDid(payload.iss);
-  if (!didDoc) {
-    throw new SpaceTokenError(
-      `could not resolve ${payload.iss}`,
-      'DidNotFound',
-    );
-  }
-  const didKey = atprotoSigningKey(didDoc, payload.iss);
   const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const sig = decodeSig(sigB64);
 
-  let valid;
-  try {
-    valid = await verifier.verify(didKey, signingInput, decodeSig(sigB64));
-  } catch (err) {
-    throw new SpaceTokenError(
-      `could not verify service token: ${err instanceof Error ? err.message : String(err)}`,
-      'BadJwtSignature',
-    );
-  }
-  if (!valid) {
-    throw new SpaceTokenError(
-      'invalid service token signature',
-      'BadJwtSignature',
-    );
+  /**
+   * @param {boolean} forceRefresh
+   * @returns {Promise<{didKey: string, valid: boolean}>}
+   */
+  const matchesSignature = async (forceRefresh) => {
+    const didDoc = await resolveDid(payload.iss, { forceRefresh });
+    if (!didDoc) {
+      throw new SpaceTokenError(
+        `could not resolve ${payload.iss}`,
+        'DidNotFound',
+      );
+    }
+    const didKey = atprotoSigningKey(didDoc, payload.iss);
+    assertKeyAlg(didKey, header.alg);
+    try {
+      return {
+        didKey,
+        valid: await verifier.verify(didKey, signingInput, sig),
+      };
+    } catch (err) {
+      throw new SpaceTokenError(
+        `could not verify service token: ${err instanceof Error ? err.message : String(err)}`,
+        'BadJwtSignature',
+      );
+    }
+  };
+
+  const first = await matchesSignature(false);
+  if (!first.valid) {
+    // A resolver that holds its answers can name a key the caller has rotated
+    // away from, and the token is signed by the current one.
+    const fresh = await matchesSignature(true);
+    if (fresh.didKey === first.didKey || !fresh.valid) {
+      throw new SpaceTokenError(
+        'invalid service token signature',
+        'BadJwtSignature',
+      );
+    }
   }
 
   return { iss: payload.iss };
@@ -131,12 +153,12 @@ export async function verifyServiceAuth({
  * @param {string} opts.iss - our DID
  * @param {string} opts.aud - the service we are calling
  * @param {string} opts.lxm - the method, so the token cannot be replayed elsewhere
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} opts.signer
+ * @param {import('./token.js').SpaceSigner} opts.signer
  * @returns {Promise<string>}
  */
 export async function createServiceAuth({ iss, aud, lxm, signer }) {
   const now = Math.floor(Date.now() / 1000);
-  const header = { typ: 'JWT', alg: 'ES256' };
+  const header = { typ: 'JWT', alg: signerAlg(signer) };
   const payload = {
     iss,
     aud,

package/src/token.d.ts

@@ -4,20 +4,38 @@ export declare const SPACE_TOKEN_TYPES: {
         kid: string;
         expiresInSec: number;
         requireAud: boolean;
+        requireCnf: boolean;
     };
     credential: {
         typ: string;
         kid: string;
         expiresInSec: number;
         requireAud: boolean;
+        requireCnf: boolean;
     };
     clientAttestation: {
         typ: string;
         kid: undefined;
         expiresInSec: number;
         requireAud: boolean;
+        requireCnf: boolean;
     };
 };
+export type SpaceSigner = {
+    sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    /**
+     * - p256 when absent
+     */
+    curve?: 'p256' | 'secp256k1';
+};
+/**
+ * The JWT `alg` for a signer's curve. A verifier resolves the issuer's key,
+ * reads its type, and refuses a header that names another algorithm before it
+ * checks the signature. So a secp256k1 key must stamp ES256K.
+ * @param {SpaceSigner} signer
+ * @returns {string}
+ */
+export declare function signerAlg(signer: SpaceSigner): string;
 export declare class SpaceTokenError extends Error {
     code: string;
     /**
@@ -26,6 +44,18 @@ export declare class SpaceTokenError extends Error {
      */
     constructor(message: string, code?: string);
 }
+/**
+ * Refuse a token whose header names an algorithm the issuer's key cannot
+ * produce. The signature would verify anyway, since the curve comes from the
+ * resolved key rather than the header. The reference implementation rejects
+ * the mismatch, so a token this server accepts has to be one the rest of the
+ * ecosystem accepts too.
+ *
+ * @param {string} didKey
+ * @param {string} alg - the token header's `alg`
+ * @throws {SpaceTokenError}
+ */
+export declare function assertKeyAlg(didKey: string, alg: string): void;
 export type SpaceTokenPayload = {
     iss: string;
     /**
@@ -36,6 +66,12 @@ export type SpaceTokenPayload = {
     iat: number;
     exp: number;
     jti: string;
+    /**
+     * - the key the holder must prove possession of
+     */
+    cnf?: {
+        jkt: string;
+    };
 };
 export type SpaceTokenHeader = {
     alg: string;
@@ -44,20 +80,19 @@ export type SpaceTokenHeader = {
 };
 /**
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
- * @param {{iss: string, sub: string, aud?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
- * @param {{sign: (bytes: Uint8Array) => Promise<Uint8Array>}} signer
+ * @param {{iss: string, sub: string, aud?: string, dpopJkt?: string, expiresInSec?: number, kid?: string, alg?: string}} opts
+ * @param {SpaceSigner} signer
  * @returns {Promise<string>}
  */
 export declare function createSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, opts: {
     iss: string;
     sub: string;
     aud?: string;
+    dpopJkt?: string;
     expiresInSec?: number;
     kid?: string;
     alg?: string;
-}, signer: {
-    sign: (bytes: Uint8Array) => Promise<Uint8Array>;
-}): Promise<string>;
+}, signer: SpaceSigner): Promise<string>;
 /**
  * Structural validation only, no signature check. This is as far as we go for
  * client attestations, whose key comes from the client's JWKS rather than a DID
@@ -77,15 +112,16 @@ export declare function parseSpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, jw
  * @param {keyof typeof SPACE_TOKEN_TYPES} type
  * @param {string} jwt
  * @param {Object} opts
- * @param {(iss: string, kid?: string) => Promise<string>} opts.getSigningKey
- *   - resolves the issuer to a did:key. Given `kid` so it can honour the key id.
+ * @param {(iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>} opts.getSigningKey
+ *   - resolves the issuer to a did:key. Given `kid` so it can honour the key
+ *   id, and `forceRefresh` to read past a held answer after a signature fails.
  * @param {import('@pdsjs/core/ports').SignatureVerifierPort} opts.verifier
  * @param {string} [opts.aud] - required audience, when the caller knows it
  * @param {string} [opts.sub] - required subject, when the caller knows it
  * @returns {Promise<{header: SpaceTokenHeader, payload: SpaceTokenPayload}>}
  */
 export declare function verifySpaceToken(type: keyof typeof SPACE_TOKEN_TYPES, jwt: string, opts: {
-    getSigningKey: (iss: string, kid?: string) => Promise<string>;
+    getSigningKey: (iss: string, kid?: string, forceRefresh?: boolean) => Promise<string>;
     verifier: import('@pdsjs/core/ports').SignatureVerifierPort;
     aud?: string;
     sub?: string;