@adonis-agora/collaboration 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # @adonis-agora/collaboration
 
+## 0.13.0
+
+### Minor Changes
+
+- 50016c7: A `load` hook per document, and a public API for the live document.
+  
+  `documents` entries take a `load({ docName, params })` — the document's **first** content, asked
+  for only when the storage has never stored that name, and persisted before the document is served.
+  Return the engine's binary state (`Y.encodeStateAsUpdate`, `A.save`), a `Y.Doc` on the Yjs engine,
+  or `null` for "nothing to seed"; `params` is typed from the pattern key exactly like `authorize`'s.
+  It runs once per document rather than once per connection, a throw is reported and opens the
+  document empty instead of failing the handshake, and two connections racing on a new document seed
+  it once. Both self-hosted engines have it.
+  
+  It exists because the alternative is not "the app seeds it": it is "the app seeds it from a request
+  it believes precedes the WebSocket". Losing that race is destructive rather than merely wrong — the
+  editor mounts against an empty CRDT document, that is what it shows, and the first autosave writes
+  the emptiness over the text in the database.
+  
+  `CollaborationManager` gains `withLiveDocument({ docName, run })`, `hasLiveDocument({ docName })`
+  and `getVersionState({ docName, versionId })`. `withLiveDocument` lends the real in-process
+  document to a callback — an external change (a Drive webhook, a cron) has to merge into the
+  instance people are typing into, and `getDocumentState` only ever hands out a copy — and answers
+  `{ live: true, value }` or `{ live: false, reason }`, so a document nobody has open, or one on an
+  engine that syncs elsewhere, is an answer instead of an invalid cast. The app that needed this was
+  reaching `manager.drivers.get('yjs').liveDoc(name)` through a cast onto two private fields.
+  
+  Fixes a silent bug in the Yjs driver on the way: `onLoadDocument` returned `{ document }`, the
+  Hocuspocus v1 shape, and Hocuspocus 4 applies the hook's result only when it is a `Y.Doc` or a
+  `Uint8Array` — so the persisted state was read, handed to a branch that ignored it, and every
+  socket got an empty document. Only a test calling the hook directly could still see it "work".
+  
+  `YjsDriver.liveDoc` and `YjsDriver.versionState` were private; they are now `liveDocument` and
+  `getVersionState`, the latter on the `CollaborationDriver` contract (implemented by all three
+  drivers). Nothing on `CollaborationManager` changed shape — `getDocumentState`, `getDocumentText`,
+  `listVersions` and the rest keep working exactly as before.
+- 50016c7: `issueCollaborationToken` and `initialTokens` — the token round-trip in front of the socket, removed.
+  
+  Opening a document was two serialized requests: `GET /collaboration/token`, and only then the
+  WebSocket. Nothing of the text could arrive until both finished — and the first of them went to the
+  server that had just rendered the page and already knew the whole answer.
+  
+  - **Server.** `issueCollaborationToken({ ctx, docName })` (or `{ user, docName }`) issues the
+    credential outside the route, for a controller to hand to the page it is rendering. It runs
+    `authorize`, resolves the document's engine through the manager and builds `wsUrl` through the
+    same function the endpoint calls — a token minted from a controller is byte-for-byte the one the
+    route would have issued for that caller. A shortcut that skipped the permission check because it
+    was reached from a controller would be a hole, not a shortcut. It throws (`CollabUnauthorizedError`,
+    `CollabForbiddenError`) rather than returning a response: in a page controller there is none to
+    return, and a render that fails is better than an editor shown to someone who may not read it.
+  - **Client.** `<CollaborationProvider initialTokens={{ [docName]: collabToken }}>` and
+    `useCollabDoc({ docName, token })`. The transport is built at mount with no HTTP request in front
+    of it.
+  - **Used once, deliberately.** Reconnects still fetch a fresh token: a credential minted at render
+    time is exactly the one that has expired by the time a socket drops, and re-fetching is what
+    re-runs `authorize` and makes revocation take effect. A pre-issued token that is malformed or
+    already dead is discarded and the session fetches one as it always did — a stale page prop can
+    cost the first paint, never the connection.
+  - `IssuedToken` (and the `/token` response) gained `expiresAt` for the formats that have an expiry,
+    so the client can recognise a dead page prop without opening a socket to find out. The self-hosted
+    base64 format still has none: `authorize` re-runs on the handshake, so it is a claim, not a grant
+    with a clock.
+  
+  Nothing changes for an app that passes no token: same request, same order, same behaviour.
+- 50016c7: **BREAKING — security.** The self-hosted token is a signed credential now, not an unsigned claim.
+  
+  `issueToken` used to return `base64(JSON.stringify({ userId }))` for the `yjs` and `automerge`
+  engines, and the drivers accepted anything that decoded to an object with a `userId` in it. That is
+  not a credential: **a client with no session, no cookie and no login could connect with
+  `base64({"userId":"<someone else's id>"})`, be authorized as that person by the app's own
+  `authorize` rule, and write into their document.** Verified against the published library, not
+  theorised. The token also never expired and could not be revoked, and the WebSocket upgrade runs
+  outside the HTTP middleware stack, so no app-side middleware was standing in front of it.
+  
+  If you run `yjs` or `automerge` with `@adonis-agora/collaboration` ≤ 0.12, treat this as an
+  urgent upgrade: any document reachable to an attacker who can guess a user id and a document name
+  was readable and writable by them.
+  
+  **What changed**
+  
+  - The self-hosted token is an HS256 JWT over `{ userId, docName, user?, iat, exp }`, the same wire
+    format the edge already used. The handshake checks the **signature**, the **expiry** (5 minutes,
+    `COLLAB_TOKEN_TTL_SECONDS`, matching the edge) and the **document** before `authorize` is
+    consulted at all — a token issued for one document does not open another, since the client is the
+    one choosing the name it connects to. Signature comparison is constant-time.
+  - Both self-hosted drivers verify: `YjsDriver.onAuthenticate` and the `AutomergeDriver` upgrade
+    handler (which now answers `4001` for a token that fails verification and `4503` when the server
+    has no key).
+  - Presence no longer re-decodes the raw token. The Yjs driver publishes the verified identity as the
+    connection context and fills the roster from it in `connected`; the old `onConnect` path decoded
+    `?token=` a second time, unauthenticated, so a forged name reached the roster even with a checked
+    handshake.
+  - `verifyPartyKitToken` takes the expected `docName` and enforces it, and the published worker
+    template compares the claim against the room it is connecting to. The edge had the same hole: the
+    signature was checked, the room was not.
+  - `IssuedToken.expiresAt` is now reported for self-hosted tokens too, so a pre-issued page prop can
+    be discarded by the client without opening a socket.
+  
+  **What you have to do**
+  
+  - Nothing, in a normal AdonisJS app: the signing key is derived from `appKey` (domain-separated), so
+    a project with `APP_KEY` set keeps working. Set `tokenSecret` in `config/collaboration.ts` for a
+    dedicated key.
+  - **If you construct `CollaborationManager` yourself**, pass `tokenSecret` — or run inside a booted
+    app so `appKey` is readable. With no key anywhere the library refuses to issue *and* refuses to
+    accept tokens (`CollabTokenSecretMissingError`, naming what to set). There is deliberately no flag
+    to accept the old format: it would reopen exactly this hole.
+  - **If you build a driver directly**, `SelfHostedDriverOptions.tokenSecret` is required.
+  - Tokens in the old format stop being accepted. Connected clients reconnect and fetch a new one, so
+    the visible cost of upgrading is one reconnect.
+  - `parseLegacyToken` is gone. `verifyCollabToken(token, secret, docName)` and
+    `verifySelfHostedToken(token, docName, secret?)` replace it; `signCollabToken`,
+    `resolveTokenSecret` and `COLLAB_TOKEN_TTL_SECONDS` are exported alongside them.
+    `PARTYKIT_TOKEN_TTL_SECONDS` still exists and is the same number.
+
+### Patch Changes
+
+- 50016c7: `defaultResolveUser` answers 401 for a caller the app considers authenticated (authkit).
+  
+  The resolver exists so that no app has to bolt a global middleware onto a hardcoded `/collaboration`
+  prefix: it calls `check()`/`authenticate()` itself and then reads `ctx.auth.user`. But
+  `@adonis-agora/authkit` resolves the user **on demand** — `check()` verifies the session and returns
+  `true`, and `ctx.auth.user` stays `undefined` forever, because the user only materialises when
+  something asks for it. So the routes 401'd, and every app hitting this wrote the same three-line
+  `resolveUser` calling `getUserOrFail()` by hand — the same call its own controllers make.
+  
+  It now asks: after `check()`/`authenticate()`, when `auth.user` is still empty it tries `getUser()`
+  (absence reported by returning nothing) and then `getUserOrFail()` (absence reported by throwing).
+  Both steps are needed — one auth stack fills `user` as a side effect, another only answers a direct
+  question, and the point of this resolver is that no app has to know which one it installed.
+  
+  Still fails closed, and still never 500s: a throwing `getUserOrFail()` is an absent user and a 401,
+  and an id that stringifies to nothing is a 401 too — an "empty" caller must never reach `authorize`,
+  where a blank id could match a rule.
+  
+  A patch: no API changed and no app needs to do anything. A hand-written `resolveUser` keeps working
+  and can now be deleted.
+
+## 0.12.0
+
+### Minor Changes
+
+- e911a53: `defineCollection(prefix, declaration?)` and a boot-time warning for patterns without a `:segment`.
+  
+  A `documents` pattern only matches many documents when it has a `:segment` — a bare `'whiteboards'`
+  matches exactly one document named `whiteboards`, and `whiteboards/42` falls through to the globals.
+  That rule lived only inside the matcher, and getting it wrong was silent.
+  
+  - `...defineCollection('whiteboards', { engine, authorize })` declares `'whiteboards/:id'` with
+    `params.id` typed, so the common shape cannot be written without the `:id`. The prefix is the
+    literal part of the name; a `:param` or a leading/trailing `/` throws.
+  - `CollaborationManager` warns once at boot for every declared pattern that has no `:segment`,
+    naming the pattern and the fix (`logger.warn` when the installed logger has one, else
+    `console.warn`). `CollabLogger` gains an optional `warn`.
+  - `documentPatternParams(pattern)` and `reportCollaborationWarning` are exported.
+
 ## 0.11.0
 
 ### Minor Changes

package/dist/providers/collaboration_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collaboration_provider.d.ts","sourceRoot":"","sources":["../../providers/collaboration_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAS/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA4B;IAGnC,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAF7C,OAAO,CAAC,MAAM,CAAC,CAAyB;IAExC,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAEjD,QAAQ,SA4BP;IAEK,IAAI,kBAuCT;IAEK,KAAK,kBAwBV;IAEK,QAAQ,kBAIb;CACF"}
+{"version":3,"file":"collaboration_provider.d.ts","sourceRoot":"","sources":["../../providers/collaboration_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAS/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA4B;IAGnC,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAF7C,OAAO,CAAC,MAAM,CAAC,CAAyB;IAExC,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAEjD,QAAQ,SAgCP;IAEK,IAAI,kBAuCT;IAEK,KAAK,kBAwBV;IAEK,QAAQ,kBAIb;CACF"}

package/dist/providers/collaboration_provider.js

@@ -49,6 +49,10 @@ export default class CollaborationServiceProvider {
                 path: config.path ?? '/collaboration',
                 debounce: config.debounce ?? 2000,
                 ...(config.storage ? { storage: config.storage } : {}),
+                // Absent means "derive from appKey" — the manager resolves it, and it
+                // must be the manager doing so, because the token route asks it for
+                // the same key.
+                ...(config.tokenSecret ? { tokenSecret: config.tokenSecret } : {}),
                 ...(config.redisUrl ? { redis: { url: config.redisUrl } } : {}),
                 ...(config.partykit ? { partykit: config.partykit } : {}),
             };

package/dist/providers/collaboration_provider.js.map

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

package/dist/src/auth/secret.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where the signing key of a self-hosted collaboration token comes from.
+ *
+ * One resolver for both ends of the credential — the issuer (`issueToken`,
+ * behind `GET /collaboration/token` and `issueCollaborationToken`) and the
+ * verifier (the drivers' handshake). They MUST read the same value: a token
+ * signed with one key and checked against another is not a security failure,
+ * it is a total outage where every handshake is refused and nothing in the
+ * logs says why.
+ */
+/**
+ * A secret, or a way to get one.
+ *
+ * The function form exists because the manager resolves its key lazily: the
+ * default source is the AdonisJS `appKey`, which only exists once the app has
+ * booted, and a driver is built before the first document is ever opened.
+ */
+export type CollabTokenSecret = string | (() => string | Promise<string>);
+/**
+ * Thrown when nothing anywhere declares a signing key.
+ *
+ * Fails closed, and says exactly what to set. The alternative — falling back
+ * to an unsigned token when the key is missing — is the hole this whole
+ * module exists to close: it would turn a misconfiguration into a server that
+ * accepts `base64({"userId":"<anyone>"})` from an unauthenticated client.
+ */
+export declare class CollabTokenSecretMissingError extends Error {
+    constructor();
+}
+/**
+ * The key both ends of the credential use — the first source that has one:
+ *
+ * 1. what the caller passed (`CollaborationManager`'s `tokenSecret` option —
+ *    the path a test or a non-Adonis embedder takes);
+ * 2. `tokenSecret` in `config/collaboration.ts`;
+ * 3. the app's `appKey`, domain-separated — so a normal AdonisJS app needs no
+ *    configuration at all, which is the only way a security default actually
+ *    gets adopted.
+ *
+ * Nothing found is an error, never a fallback. See
+ * {@link CollabTokenSecretMissingError}.
+ *
+ * Idempotent for any explicit secret: resolving an already-resolved key
+ * returns it unchanged, so the manager can memoize one key and let the issuer
+ * and the driver each resolve it again without the two drifting apart.
+ */
+export declare function resolveTokenSecret(source?: CollabTokenSecret): Promise<string>;
+//# sourceMappingURL=secret.d.ts.map

package/dist/src/auth/secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../../../src/auth/secret.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,cAQC;CACF;AAyDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CASpF"}

package/dist/src/auth/secret.js

@@ -0,0 +1,95 @@
+import { createHmac } from 'node:crypto';
+/**
+ * Thrown when nothing anywhere declares a signing key.
+ *
+ * Fails closed, and says exactly what to set. The alternative — falling back
+ * to an unsigned token when the key is missing — is the hole this whole
+ * module exists to close: it would turn a misconfiguration into a server that
+ * accepts `base64({"userId":"<anyone>"})` from an unauthenticated client.
+ */
+export class CollabTokenSecretMissingError extends Error {
+    constructor() {
+        super('[@adonis-agora/collaboration] no signing secret available — refusing to issue or accept collaboration tokens. ' +
+            'In an AdonisJS app this is normally the app key and needs no configuration — check that APP_KEY is set ' +
+            'and config/app.ts exports `appKey`. Outside an app (or to use a dedicated key), set `tokenSecret` in ' +
+            'config/collaboration.ts, or pass `tokenSecret` to the CollaborationManager.');
+        this.name = 'CollabTokenSecretMissingError';
+    }
+}
+/**
+ * Domain separation for the key derived from `appKey`.
+ *
+ * `appKey` already signs cookies and encrypts session payloads. Signing
+ * collaboration tokens with the very same bytes would let a value produced by
+ * one of those subsystems be replayed at another; one HMAC over a fixed label
+ * makes the key used here unusable anywhere else. `v1` is there so a future
+ * format change can invalidate every outstanding token by changing one string.
+ *
+ * Applied ONLY to the `appKey` fallback, never to a secret someone configured
+ * on purpose — which is what makes {@link resolveTokenSecret} idempotent, and
+ * therefore safe to run over a key it already resolved. The manager memoizes
+ * its key and hands it to both the issuer and the driver, and each of them
+ * resolves again; a derivation on every pass would give the two ends
+ * different keys and refuse every handshake.
+ */
+const APP_KEY_DOMAIN = '@adonis-agora/collaboration:self-hosted-token:v1';
+/** The app's `appKey`, domain-separated, when running inside a booted app. */
+async function readAppKey() {
+    try {
+        // Dynamic + optional: unavailable in plain unit tests, and in any process
+        // that builds a manager without an AdonisJS app around it.
+        const app = (await import('@adonisjs/core/services/app')).default;
+        const key = app.config.get('app.appKey', undefined);
+        // AdonisJS 6 wraps it in a `Secret<string>` so it never lands in a log by
+        // accident; older apps (and tests) keep a plain string.
+        const raw = typeof key === 'string'
+            ? key
+            : typeof key?.release === 'function'
+                ? key.release()
+                : undefined;
+        if (typeof raw !== 'string' || raw.length === 0)
+            return undefined;
+        return createHmac('sha256', raw).update(APP_KEY_DOMAIN).digest('base64url');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `tokenSecret` declared in `config/collaboration.ts`, when there is one. */
+async function readConfiguredSecret() {
+    try {
+        const app = (await import('@adonisjs/core/services/app')).default;
+        const secret = app.config.get('collaboration.tokenSecret', undefined);
+        return typeof secret === 'string' && secret.length > 0 ? secret : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The key both ends of the credential use — the first source that has one:
+ *
+ * 1. what the caller passed (`CollaborationManager`'s `tokenSecret` option —
+ *    the path a test or a non-Adonis embedder takes);
+ * 2. `tokenSecret` in `config/collaboration.ts`;
+ * 3. the app's `appKey`, domain-separated — so a normal AdonisJS app needs no
+ *    configuration at all, which is the only way a security default actually
+ *    gets adopted.
+ *
+ * Nothing found is an error, never a fallback. See
+ * {@link CollabTokenSecretMissingError}.
+ *
+ * Idempotent for any explicit secret: resolving an already-resolved key
+ * returns it unchanged, so the manager can memoize one key and let the issuer
+ * and the driver each resolve it again without the two drifting apart.
+ */
+export async function resolveTokenSecret(source) {
+    const explicit = typeof source === 'function' ? await source() : source;
+    const secret = (explicit && explicit.length > 0 ? explicit : undefined) ??
+        (await readConfiguredSecret()) ??
+        (await readAppKey());
+    if (!secret)
+        throw new CollabTokenSecretMissingError();
+    return secret;
+}
+//# sourceMappingURL=secret.js.map

package/dist/src/auth/secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../../../src/auth/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsBzC;;;;;;;GAOG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD;QACE,KAAK,CACH,gHAAgH;YAC9G,yGAAyG;YACzG,uGAAuG;YACvG,6EAA6E,CAChF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,cAAc,GAAG,kDAAkD,CAAC;AAE1E,8EAA8E;AAC9E,KAAK,UAAU,UAAU;IACvB,IAAI,CAAC;QACH,0EAA0E;QAC1E,2DAA2D;QAC3D,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC,CAAC,OAEzD,CAAC;QACF,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACpD,0EAA0E;QAC1E,wDAAwD;QACxD,MAAM,GAAG,GACP,OAAO,GAAG,KAAK,QAAQ;YACrB,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,OAAQ,GAA+C,EAAE,OAAO,KAAK,UAAU;gBAC/E,CAAC,CAAE,GAAkC,CAAC,OAAO,EAAE;gBAC/C,CAAC,CAAC,SAAS,CAAC;QAClB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAClE,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,KAAK,UAAU,oBAAoB;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC,CAAC,OAEzD,CAAC;QACF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAC;QACtE,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAA0B;IACjE,MAAM,QAAQ,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,MAAM,MAAM,GACV,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QACxD,CAAC,MAAM,oBAAoB,EAAE,CAAC;QAC9B,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC;IAEvB,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,6BAA6B,EAAE,CAAC;IACvD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/auth/token.d.ts

@@ -1,12 +1,21 @@
 import type { CollabConnectionContext, CollabPermission, PartyKitConfig } from '../types.js';
+import { type CollabTokenSecret } from './secret.js';
 /**
  * The token/auth module — the single seam for issuing and verifying
  * collaboration credentials.
  *
- * Two wire formats, chosen by engine:
- *  - `partykit` → HS256 JWT (verified by the edge worker via WebCrypto)
- *  - self-hosted (`yjs`/`automerge`) → legacy base64 JSON payload accepted
- *    by the driver handshake
+ * **One wire format, two secrets.** Both the edge (`partykit`) and the
+ * self-hosted engines (`yjs`/`automerge`) carry an HS256 JWT bound to one
+ * document and valid for {@link COLLAB_TOKEN_TTL_SECONDS}; they differ only
+ * in which key signs it (the worker's `jwtSecret` vs. the app's own key — see
+ * `auth/secret.ts`) and therefore in who can verify it.
+ *
+ * It used to differ in more than that: the self-hosted format was a bare
+ * base64 of the connection context, unsigned and without an expiry. That is
+ * not a credential — anyone could send `base64({"userId":"<victim>"})` with no
+ * session, no cookie and no login, and the driver would authorize the
+ * handshake as that user and let them write. The format is gone; a token that
+ * is not signed by this server is not accepted by it.
  *
  * `issueToken` also enforces `config.authorize` on the REST path — the
  * permission seam must hold outside the WebSocket handshake too.
@@ -16,26 +25,97 @@ export interface TokenIssuerConfig {
     /** WS path of the embedded Hocuspocus server (self-hosted engines). */
     path?: string;
     partykit?: Partial<Pick<PartyKitConfig, 'roomHost' | 'jwtSecret' | 'party'>>;
+    /**
+     * Signing key for the self-hosted format. Resolved through
+     * {@link resolveTokenSecret}, so the issuer and the driver that verifies
+     * the token read the same source and cannot drift apart.
+     */
+    tokenSecret?: CollabTokenSecret;
 }
 /** Minimal authorize contract — mirrors CollaborationConfig.authorize. */
 export type AuthorizeFn = (ctx: CollabConnectionContext, docName: string) => Promise<CollabPermission>;
-/** Signs a minimal HS256 JWT — no external dependency. */
-export declare function signPartyKitToken(payload: {
+/**
+ * Lifetime of a collaboration token, in seconds.
+ *
+ * Named rather than inlined because three places need the same number: the
+ * signature's `exp`, the `expiresAt` the issuer reports back so a caller
+ * holding the token ahead of time can tell it is already dead, and the
+ * client's decision to discard a page-prop token instead of opening a socket
+ * with it.
+ *
+ * Five minutes is what the edge format has always used, and the self-hosted
+ * one now matches it deliberately: the token is spent within milliseconds of
+ * being issued (the browser fetches it and connects), and a long-lived one
+ * would only widen the window in which a leaked URL still opens a document.
+ * The socket it opens is not cut short by expiry — `authorize` runs once at
+ * the handshake and the connection then lives on its own.
+ */
+export declare const COLLAB_TOKEN_TTL_SECONDS = 300;
+/**
+ * The old name of {@link COLLAB_TOKEN_TTL_SECONDS}, kept because it is public
+ * API that apps and the worker template already read. One number, because one
+ * wire format: a second constant would eventually drift from this one and the
+ * drift would show up as tokens that expire earlier than the client thinks.
+ */
+export declare const PARTYKIT_TOKEN_TTL_SECONDS = 300;
+/** What a signed collaboration token carries. */
+export interface CollabTokenPayload {
     userId: string;
+    /**
+     * The document the credential opens — and only that one. Verified against
+     * the document actually being connected to; without that check a token
+     * legitimately issued for a document the caller may read would also open
+     * every document they may not.
+     */
     docName: string;
+    /** Presence metadata, carried so the roster does not need a second lookup. */
     user?: {
         name?: string;
         avatarUrl?: string | null;
     };
-}, secret: string, expiresInSeconds?: number): string;
-/** Verifies signature + expiry of a token issued by {@link signPartyKitToken}. */
-export declare function verifyPartyKitToken(token: string, secret: string): {
-    userId: string;
-    docName: string;
+}
+/** Signs a minimal HS256 JWT — no external dependency. */
+export declare function signCollabToken(payload: CollabTokenPayload, secret: string, expiresInSeconds?: number): string;
+/**
+ * Verifies signature, expiry and document binding of a token issued by
+ * {@link signCollabToken}. Returns `null` for every failure — a verifier that
+ * distinguishes "bad signature" from "wrong document" in its return value
+ * invites a caller to treat one of them as recoverable.
+ *
+ * `expectedDocName` is required rather than optional on purpose: every caller
+ * knows which document is being opened, and an optional argument is one a
+ * caller forgets — which is exactly the bug this parameter exists to prevent.
+ */
+export declare function verifyCollabToken(token: string, secret: string, expectedDocName: string): (CollabTokenPayload & {
     exp: number;
-} | null;
-/** Parses the legacy base64 payload used by self-hosted driver handshakes. */
-export declare function parseLegacyToken(token: string): CollabConnectionContext | null;
+}) | null;
+/** The connection context a verified token stands for. */
+export declare function tokenContext(payload: CollabTokenPayload): CollabConnectionContext;
+/**
+ * Verifies a self-hosted token against the key resolved from the app —
+ * what a driver's handshake calls.
+ *
+ * Throws (rather than returning `null`) when there is no key to verify
+ * against: a missing secret is a misconfiguration of the server, not a bad
+ * token from the client, and the two must not produce the same message in the
+ * logs. Either way nothing is authenticated.
+ */
+export declare function verifySelfHostedToken(token: string, docName: string, source: CollabTokenSecret | undefined): Promise<CollabConnectionContext | null>;
+/**
+ * Signs the edge JWT. Same format and same TTL as every other collaboration
+ * token; the difference is the key, which the PartyKit worker holds
+ * (`COLLAB_JWT_SECRET`) and this process only shares with it.
+ */
+export declare const signPartyKitToken: typeof signCollabToken;
+/**
+ * Verifies an edge JWT, including its document binding.
+ *
+ * The worker template runs the same three checks in WebCrypto — signature,
+ * `exp`, and `docName` against the room being connected to. Keep them in
+ * step: the room is the document, so a token that opens a room it was not
+ * issued for is the same hole on the edge that it is here.
+ */
+export declare const verifyPartyKitToken: typeof verifyCollabToken;
 /** Builds the browser-facing WebSocket URL for an engine. */
 export declare function buildWsUrl(config: TokenIssuerConfig, docName: string): string;
 /** Result of a successful token issue. */
@@ -43,6 +123,23 @@ export interface IssuedToken {
     token: string;
     wsUrl: string;
     engine: string;
+    /**
+     * Epoch milliseconds after which the credential stops being accepted.
+     *
+     * Reported for every engine: both wire formats are signed JWTs with an
+     * `exp`, and the handshake refuses a token past it. (It was absent for the
+     * self-hosted format while that format had no expiry — an unsigned claim
+     * about identity that never died. It is a real credential now.)
+     *
+     * It exists for the benefit of a token handed to the browser *before* it
+     * connects (a server-rendered page prop). Such a token can sit in the HTML
+     * for as long as the tab is open, and the client has to be able to tell
+     * "already dead" from "worth trying" without opening a socket to find out.
+     *
+     * Optional on the type because a custom issuer may not have one to report;
+     * nothing this package issues omits it.
+     */
+    expiresAt?: number;
 }
 /** Thrown when authorize() denies read access for the document. */
 export declare class CollabForbiddenError extends Error {

package/dist/src/auth/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/auth/token.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7F;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAC9E;AAED,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,uBAAuB,EAC5B,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,EACjG,MAAM,EAAE,MAAM,EACd,gBAAgB,SAAM,GACrB,MAAM,CAQR;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoBzD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAO9E;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAS7E;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mEAAmE;AACnE,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAG5C;CACF;AAED;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,OAAO,EAAE,MAAM;aACN,KAAK,CAAC,EAAE,OAAO;IAFnC,YACW,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,EAIlC;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC1C,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,WAAW,CAAC,CA+BtB"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/auth/token.ts"],"names":[],"mappings":"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"}