@ractive-ch/tab-mcp 0.0.0-stage → 0.1.0-alpha.0

package/store/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The token store (DEC-030, DEC-041): where the relay keeps grants and the
+ * hashes of access and refresh tokens. Implementations: `MemoryTokenStore`,
+ * `SqliteTokenStore`, or the library user's own (Prisma, Redis, libSQL, …),
+ * checked with the conformance suite in `@ractive-ch/tab-mcp/testing`.
+ *
+ * Guarantees every implementation must give:
+ * - Records are keyed by `hash`, the SHA-256 of the token; plain tokens never
+ *   reach the store.
+ * - `put` inserts or replaces the record with the same hash.
+ * - `get` returns the record even when it is expired or used; the caller
+ *   decides. It returns `undefined` after `revoke` or `deleteExpired` removed it.
+ * - `markUsed` is atomic: for one hash, exactly one call ever returns `true`,
+ *   even when several run at the same time.
+ * - `revoke` leaves a tombstone at least until `keepUntil`: until then `put` refuses
+ *   (returns `false`, stores nothing) a record of a revoked grant, or of a
+ *   grant of a revoked address created at or before the revocation. Checking
+ *   the tombstone and inserting must be atomic, so tokens minted by a refresh
+ *   that raced a revocation can never outlive it.
+ * - Times are milliseconds since the Unix epoch.
+ */
+export type TokenKind = "access" | "refresh";
+export interface TokenRecord {
+    /** SHA-256 of the token, base64url without padding. */
+    hash: string;
+    kind: TokenKind;
+    grantId: string;
+    /** The address the grant belongs to (DEC-027). */
+    addressId: string;
+    /** The OAuth client id (the CIMD URL). */
+    clientId: string;
+    /** The client's self-declared name, for display only. */
+    clientName: string;
+    scopes: string[];
+    /** When the grant was created (the first token of the grant). */
+    grantCreatedAt: number;
+    issuedAt: number;
+    expiresAt: number;
+    /** Refresh tokens: when it was exchanged for a new one. */
+    usedAt?: number;
+}
+/** One connected AI app of an address. */
+export interface GrantSummary {
+    grantId: string;
+    clientId: string;
+    clientName: string;
+    scopes: string[];
+    createdAt: number;
+}
+export type RevokeSelector = {
+    grantId: string;
+} | {
+    addressId: string;
+};
+export interface RevokeOptions {
+    /** When the revocation happens. */
+    now: number;
+    /** Keep the tombstone until then (the longest a token issued before could live). */
+    keepUntil: number;
+}
+export interface TokenStore {
+    /**
+     * Insert or replace a token record. Returns `false`, and stores nothing,
+     * if its grant was revoked (see the tombstone rule above).
+     */
+    put(record: TokenRecord): Promise<boolean>;
+    /** The record for a token hash, or `undefined`. */
+    get(hash: string): Promise<TokenRecord | undefined>;
+    /**
+     * Mark a token as used at `now`. Returns `true` for the one call that marked
+     * it, `false` if it was already used or does not exist. Must be atomic.
+     */
+    markUsed(hash: string, now: number): Promise<boolean>;
+    /**
+     * Delete every token of a grant or of an address and leave a tombstone
+     * until `options.keepUntil`. Returns how many tokens were deleted.
+     */
+    revoke(selector: RevokeSelector, options: RevokeOptions): Promise<number>;
+    /**
+     * The grants of an address that still have a usable token at `now` (an
+     * unexpired access token or an unexpired, unused refresh token), oldest
+     * first.
+     */
+    listGrants(addressId: string, now: number): Promise<GrantSummary[]>;
+    /** Delete every record with `expiresAt <= now` and tombstones past `keepUntil`. Returns how many records. */
+    deleteExpired(now: number): Promise<number>;
+    /** Release resources (database handles). Optional. */
+    close?(): Promise<void>;
+}

package/testing.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `@ractive-ch/tab-mcp/testing`: the `TokenStore` conformance suite for
+ * `bun test` (DEC-041).
+ */
+export { tokenStoreConformance } from "./store/conformance.js";

package/testing.js

@@ -0,0 +1,204 @@
+// @bun
+// src/store/conformance.ts
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+function tokenStoreConformance(name, factory) {
+  describe(`TokenStore conformance: ${name}`, () => {
+    let store;
+    const now = 1800000000000;
+    let seq = 0;
+    const until = { now, keepUntil: now + 86400000 };
+    const record = (over = {}) => {
+      seq++;
+      return {
+        hash: `hash-${seq}`,
+        kind: "access",
+        grantId: "g_1",
+        addressId: "addr-a",
+        clientId: "https://client.example/cimd",
+        clientName: "Client",
+        scopes: ["tools"],
+        grantCreatedAt: now - 1000,
+        issuedAt: now,
+        expiresAt: now + 3600000,
+        ...over
+      };
+    };
+    beforeEach(async () => {
+      store = await factory();
+    });
+    afterEach(async () => {
+      await store.close?.();
+    });
+    test("put then get returns an equal record", async () => {
+      const r = record({ scopes: ["tools", "extra"] });
+      expect(await store.put(r)).toBe(true);
+      expect(await store.get(r.hash)).toEqual(r);
+    });
+    test("get of an unknown hash is undefined", async () => {
+      expect(await store.get("nope")).toBeUndefined();
+    });
+    test("put replaces the record with the same hash", async () => {
+      const r = record();
+      await store.put(r);
+      await store.put({ ...r, clientName: "Renamed", expiresAt: now + 5 });
+      const got = await store.get(r.hash);
+      expect(got?.clientName).toBe("Renamed");
+      expect(got?.expiresAt).toBe(now + 5);
+    });
+    test("get returns expired and used records unchanged", async () => {
+      const expired = record({ expiresAt: now - 1 });
+      const used = record({ kind: "refresh", usedAt: now - 10 });
+      await store.put(expired);
+      await store.put(used);
+      expect(await store.get(expired.hash)).toEqual(expired);
+      expect(await store.get(used.hash)).toEqual(used);
+    });
+    test("a record without usedAt comes back without the key", async () => {
+      const r = record();
+      await store.put(r);
+      const got = await store.get(r.hash);
+      expect(got !== undefined && "usedAt" in got).toBe(false);
+    });
+    test("markUsed succeeds once, then fails", async () => {
+      const r = record({ kind: "refresh" });
+      await store.put(r);
+      expect(await store.markUsed(r.hash, now + 1)).toBe(true);
+      expect(await store.markUsed(r.hash, now + 2)).toBe(false);
+      expect((await store.get(r.hash))?.usedAt).toBe(now + 1);
+    });
+    test("markUsed of an unknown hash fails", async () => {
+      expect(await store.markUsed("nope", now)).toBe(false);
+    });
+    test("concurrent markUsed calls: exactly one wins", async () => {
+      const r = record({ kind: "refresh" });
+      await store.put(r);
+      const results = await Promise.all(Array.from({ length: 10 }, (_, i) => store.markUsed(r.hash, now + i)));
+      expect(results.filter(Boolean)).toHaveLength(1);
+    });
+    test("revoke by grant deletes only that grant's tokens", async () => {
+      const a = record({ grantId: "g_a" });
+      const a2 = record({ grantId: "g_a", kind: "refresh" });
+      const b = record({ grantId: "g_b" });
+      for (const r of [a, a2, b])
+        await store.put(r);
+      expect(await store.revoke({ grantId: "g_a" }, until)).toBe(2);
+      expect(await store.get(a.hash)).toBeUndefined();
+      expect(await store.get(a2.hash)).toBeUndefined();
+      expect(await store.get(b.hash)).toEqual(b);
+    });
+    test("revoke by address deletes only that address's tokens", async () => {
+      const a = record({ addressId: "addr-a", grantId: "g_a" });
+      const b = record({ addressId: "addr-b", grantId: "g_b" });
+      await store.put(a);
+      await store.put(b);
+      expect(await store.revoke({ addressId: "addr-a" }, until)).toBe(1);
+      expect(await store.get(a.hash)).toBeUndefined();
+      expect(await store.get(b.hash)).toEqual(b);
+    });
+    test("revoke of nothing returns 0", async () => {
+      expect(await store.revoke({ grantId: "none" }, until)).toBe(0);
+    });
+    test("a revoked grant gets no new tokens until its tombstone expires", async () => {
+      await store.revoke({ grantId: "g_dead" }, until);
+      const late = record({ grantId: "g_dead", kind: "refresh" });
+      expect(await store.put(late)).toBe(false);
+      expect(await store.get(late.hash)).toBeUndefined();
+      expect(await store.put(record({ grantId: "g_alive" }))).toBe(true);
+      await store.deleteExpired(until.keepUntil);
+      expect(await store.put(record({ grantId: "g_dead" }))).toBe(true);
+    });
+    test("a revoked address refuses grants created up to the revocation, not later ones", async () => {
+      await store.revoke({ addressId: "addr-a" }, until);
+      expect(await store.put(record({ grantId: "g_before", grantCreatedAt: now }))).toBe(false);
+      expect(await store.put(record({ grantId: "g_after", grantCreatedAt: now + 1 }))).toBe(true);
+      expect(await store.put(record({
+        grantId: "g_elsewhere",
+        addressId: "addr-b",
+        grantCreatedAt: now
+      }))).toBe(true);
+    });
+    test("a put racing a revocation of its grant never survives it", async () => {
+      for (let i = 0;i < 20; i++) {
+        const r = record({ grantId: `g_race_${i}`, kind: "refresh" });
+        await Promise.all([
+          store.put(r),
+          store.revoke({ grantId: r.grantId }, until)
+        ]);
+        expect(await store.get(r.hash)).toBeUndefined();
+      }
+    });
+    test("deleteExpired removes records with expiresAt <= now only", async () => {
+      const gone = record({ expiresAt: now - 1 });
+      const edge = record({ expiresAt: now });
+      const kept = record({ expiresAt: now + 1 });
+      for (const r of [gone, edge, kept])
+        await store.put(r);
+      expect(await store.deleteExpired(now)).toBe(2);
+      expect(await store.get(gone.hash)).toBeUndefined();
+      expect(await store.get(edge.hash)).toBeUndefined();
+      expect(await store.get(kept.hash)).toEqual(kept);
+    });
+    test("listGrants groups live tokens of one address by grant", async () => {
+      await store.put(record({
+        grantId: "g_new",
+        grantCreatedAt: now - 10,
+        clientName: "New"
+      }));
+      await store.put(record({
+        grantId: "g_old",
+        grantCreatedAt: now - 500,
+        clientName: "Old",
+        scopes: ["tools"]
+      }));
+      await store.put(record({
+        grantId: "g_old",
+        kind: "refresh",
+        grantCreatedAt: now - 500,
+        clientName: "Old"
+      }));
+      await store.put(record({ grantId: "g_other", addressId: "addr-b" }));
+      expect(await store.listGrants("addr-a", now)).toEqual([
+        {
+          grantId: "g_old",
+          clientId: "https://client.example/cimd",
+          clientName: "Old",
+          scopes: ["tools"],
+          createdAt: now - 500
+        },
+        {
+          grantId: "g_new",
+          clientId: "https://client.example/cimd",
+          clientName: "New",
+          scopes: ["tools"],
+          createdAt: now - 10
+        }
+      ]);
+    });
+    test("listGrants leaves out grants without a usable token", async () => {
+      await store.put(record({ grantId: "g_expired", expiresAt: now }));
+      await store.put(record({ grantId: "g_used", kind: "refresh", usedAt: now - 1 }));
+      await store.put(record({ grantId: "g_live", kind: "refresh", expiresAt: now + 1 }));
+      const grants = await store.listGrants("addr-a", now);
+      expect(grants.map((g) => g.grantId)).toEqual(["g_live"]);
+    });
+    test("listGrants of an unknown address is empty", async () => {
+      expect(await store.listGrants("nobody", now)).toEqual([]);
+    });
+    test("changing a returned record does not change the store", async () => {
+      const r = record();
+      await store.put(r);
+      const got = await store.get(r.hash);
+      if (got === undefined)
+        throw new Error("missing");
+      got.scopes.push("mutated");
+      got.expiresAt = 0;
+      expect(await store.get(r.hash)).toEqual(r);
+    });
+  });
+}
+export {
+  tokenStoreConformance
+};
+
+//# debugId=894AE659D8460D9664756E2164756E21
+//# sourceMappingURL=testing.js.map

package/testing.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/store/conformance.ts"],
+  "sourcesContent": [
+    "import { afterEach, beforeEach, describe, expect, test } from \"bun:test\";\nimport type { TokenRecord, TokenStore } from \"./types.ts\";\n\n/**\n * The conformance suite every `TokenStore` must pass (DEC-041). Call it from a\n * `bun test` file with a factory that returns a fresh, empty store:\n *\n * ```ts\n * import { tokenStoreConformance } from \"@ractive-ch/tab-mcp/testing\";\n * tokenStoreConformance(\"RedisTokenStore\", async () => new RedisTokenStore(…));\n * ```\n */\nexport function tokenStoreConformance(\n\tname: string,\n\tfactory: () => TokenStore | Promise<TokenStore>,\n): void {\n\tdescribe(`TokenStore conformance: ${name}`, () => {\n\t\tlet store: TokenStore;\n\t\tconst now = 1_800_000_000_000;\n\t\tlet seq = 0;\n\n\t\tconst until = { now, keepUntil: now + 86_400_000 };\n\n\t\tconst record = (over: Partial<TokenRecord> = {}): TokenRecord => {\n\t\t\tseq++;\n\t\t\treturn {\n\t\t\t\thash: `hash-${seq}`,\n\t\t\t\tkind: \"access\",\n\t\t\t\tgrantId: \"g_1\",\n\t\t\t\taddressId: \"addr-a\",\n\t\t\t\tclientId: \"https://client.example/cimd\",\n\t\t\t\tclientName: \"Client\",\n\t\t\t\tscopes: [\"tools\"],\n\t\t\t\tgrantCreatedAt: now - 1000,\n\t\t\t\tissuedAt: now,\n\t\t\t\texpiresAt: now + 3_600_000,\n\t\t\t\t...over,\n\t\t\t};\n\t\t};\n\n\t\tbeforeEach(async () => {\n\t\t\tstore = await factory();\n\t\t});\n\n\t\tafterEach(async () => {\n\t\t\tawait store.close?.();\n\t\t});\n\n\t\ttest(\"put then get returns an equal record\", async () => {\n\t\t\tconst r = record({ scopes: [\"tools\", \"extra\"] });\n\t\t\texpect(await store.put(r)).toBe(true);\n\t\t\texpect(await store.get(r.hash)).toEqual(r);\n\t\t});\n\n\t\ttest(\"get of an unknown hash is undefined\", async () => {\n\t\t\texpect(await store.get(\"nope\")).toBeUndefined();\n\t\t});\n\n\t\ttest(\"put replaces the record with the same hash\", async () => {\n\t\t\tconst r = record();\n\t\t\tawait store.put(r);\n\t\t\tawait store.put({ ...r, clientName: \"Renamed\", expiresAt: now + 5 });\n\t\t\tconst got = await store.get(r.hash);\n\t\t\texpect(got?.clientName).toBe(\"Renamed\");\n\t\t\texpect(got?.expiresAt).toBe(now + 5);\n\t\t});\n\n\t\ttest(\"get returns expired and used records unchanged\", async () => {\n\t\t\tconst expired = record({ expiresAt: now - 1 });\n\t\t\tconst used = record({ kind: \"refresh\", usedAt: now - 10 });\n\t\t\tawait store.put(expired);\n\t\t\tawait store.put(used);\n\t\t\texpect(await store.get(expired.hash)).toEqual(expired);\n\t\t\texpect(await store.get(used.hash)).toEqual(used);\n\t\t});\n\n\t\ttest(\"a record without usedAt comes back without the key\", async () => {\n\t\t\tconst r = record();\n\t\t\tawait store.put(r);\n\t\t\tconst got = await store.get(r.hash);\n\t\t\texpect(got !== undefined && \"usedAt\" in got).toBe(false);\n\t\t});\n\n\t\ttest(\"markUsed succeeds once, then fails\", async () => {\n\t\t\tconst r = record({ kind: \"refresh\" });\n\t\t\tawait store.put(r);\n\t\t\texpect(await store.markUsed(r.hash, now + 1)).toBe(true);\n\t\t\texpect(await store.markUsed(r.hash, now + 2)).toBe(false);\n\t\t\texpect((await store.get(r.hash))?.usedAt).toBe(now + 1);\n\t\t});\n\n\t\ttest(\"markUsed of an unknown hash fails\", async () => {\n\t\t\texpect(await store.markUsed(\"nope\", now)).toBe(false);\n\t\t});\n\n\t\ttest(\"concurrent markUsed calls: exactly one wins\", async () => {\n\t\t\tconst r = record({ kind: \"refresh\" });\n\t\t\tawait store.put(r);\n\t\t\tconst results = await Promise.all(\n\t\t\t\tArray.from({ length: 10 }, (_, i) => store.markUsed(r.hash, now + i)),\n\t\t\t);\n\t\t\texpect(results.filter(Boolean)).toHaveLength(1);\n\t\t});\n\n\t\ttest(\"revoke by grant deletes only that grant's tokens\", async () => {\n\t\t\tconst a = record({ grantId: \"g_a\" });\n\t\t\tconst a2 = record({ grantId: \"g_a\", kind: \"refresh\" });\n\t\t\tconst b = record({ grantId: \"g_b\" });\n\t\t\tfor (const r of [a, a2, b]) await store.put(r);\n\t\t\texpect(await store.revoke({ grantId: \"g_a\" }, until)).toBe(2);\n\t\t\texpect(await store.get(a.hash)).toBeUndefined();\n\t\t\texpect(await store.get(a2.hash)).toBeUndefined();\n\t\t\texpect(await store.get(b.hash)).toEqual(b);\n\t\t});\n\n\t\ttest(\"revoke by address deletes only that address's tokens\", async () => {\n\t\t\tconst a = record({ addressId: \"addr-a\", grantId: \"g_a\" });\n\t\t\tconst b = record({ addressId: \"addr-b\", grantId: \"g_b\" });\n\t\t\tawait store.put(a);\n\t\t\tawait store.put(b);\n\t\t\texpect(await store.revoke({ addressId: \"addr-a\" }, until)).toBe(1);\n\t\t\texpect(await store.get(a.hash)).toBeUndefined();\n\t\t\texpect(await store.get(b.hash)).toEqual(b);\n\t\t});\n\n\t\ttest(\"revoke of nothing returns 0\", async () => {\n\t\t\texpect(await store.revoke({ grantId: \"none\" }, until)).toBe(0);\n\t\t});\n\n\t\ttest(\"a revoked grant gets no new tokens until its tombstone expires\", async () => {\n\t\t\tawait store.revoke({ grantId: \"g_dead\" }, until);\n\t\t\tconst late = record({ grantId: \"g_dead\", kind: \"refresh\" });\n\t\t\texpect(await store.put(late)).toBe(false);\n\t\t\texpect(await store.get(late.hash)).toBeUndefined();\n\t\t\texpect(await store.put(record({ grantId: \"g_alive\" }))).toBe(true);\n\t\t\tawait store.deleteExpired(until.keepUntil);\n\t\t\texpect(await store.put(record({ grantId: \"g_dead\" }))).toBe(true);\n\t\t});\n\n\t\ttest(\"a revoked address refuses grants created up to the revocation, not later ones\", async () => {\n\t\t\tawait store.revoke({ addressId: \"addr-a\" }, until);\n\t\t\texpect(\n\t\t\t\tawait store.put(record({ grantId: \"g_before\", grantCreatedAt: now })),\n\t\t\t).toBe(false);\n\t\t\texpect(\n\t\t\t\tawait store.put(\n\t\t\t\t\trecord({ grantId: \"g_after\", grantCreatedAt: now + 1 }),\n\t\t\t\t),\n\t\t\t).toBe(true);\n\t\t\texpect(\n\t\t\t\tawait store.put(\n\t\t\t\t\trecord({\n\t\t\t\t\t\tgrantId: \"g_elsewhere\",\n\t\t\t\t\t\taddressId: \"addr-b\",\n\t\t\t\t\t\tgrantCreatedAt: now,\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t).toBe(true);\n\t\t});\n\n\t\ttest(\"a put racing a revocation of its grant never survives it\", async () => {\n\t\t\tfor (let i = 0; i < 20; i++) {\n\t\t\t\tconst r = record({ grantId: `g_race_${i}`, kind: \"refresh\" });\n\t\t\t\tawait Promise.all([\n\t\t\t\t\tstore.put(r),\n\t\t\t\t\tstore.revoke({ grantId: r.grantId }, until),\n\t\t\t\t]);\n\t\t\t\texpect(await store.get(r.hash)).toBeUndefined();\n\t\t\t}\n\t\t});\n\n\t\ttest(\"deleteExpired removes records with expiresAt <= now only\", async () => {\n\t\t\tconst gone = record({ expiresAt: now - 1 });\n\t\t\tconst edge = record({ expiresAt: now });\n\t\t\tconst kept = record({ expiresAt: now + 1 });\n\t\t\tfor (const r of [gone, edge, kept]) await store.put(r);\n\t\t\texpect(await store.deleteExpired(now)).toBe(2);\n\t\t\texpect(await store.get(gone.hash)).toBeUndefined();\n\t\t\texpect(await store.get(edge.hash)).toBeUndefined();\n\t\t\texpect(await store.get(kept.hash)).toEqual(kept);\n\t\t});\n\n\t\ttest(\"listGrants groups live tokens of one address by grant\", async () => {\n\t\t\tawait store.put(\n\t\t\t\trecord({\n\t\t\t\t\tgrantId: \"g_new\",\n\t\t\t\t\tgrantCreatedAt: now - 10,\n\t\t\t\t\tclientName: \"New\",\n\t\t\t\t}),\n\t\t\t);\n\t\t\tawait store.put(\n\t\t\t\trecord({\n\t\t\t\t\tgrantId: \"g_old\",\n\t\t\t\t\tgrantCreatedAt: now - 500,\n\t\t\t\t\tclientName: \"Old\",\n\t\t\t\t\tscopes: [\"tools\"],\n\t\t\t\t}),\n\t\t\t);\n\t\t\tawait store.put(\n\t\t\t\trecord({\n\t\t\t\t\tgrantId: \"g_old\",\n\t\t\t\t\tkind: \"refresh\",\n\t\t\t\t\tgrantCreatedAt: now - 500,\n\t\t\t\t\tclientName: \"Old\",\n\t\t\t\t}),\n\t\t\t);\n\t\t\tawait store.put(record({ grantId: \"g_other\", addressId: \"addr-b\" }));\n\t\t\texpect(await store.listGrants(\"addr-a\", now)).toEqual([\n\t\t\t\t{\n\t\t\t\t\tgrantId: \"g_old\",\n\t\t\t\t\tclientId: \"https://client.example/cimd\",\n\t\t\t\t\tclientName: \"Old\",\n\t\t\t\t\tscopes: [\"tools\"],\n\t\t\t\t\tcreatedAt: now - 500,\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tgrantId: \"g_new\",\n\t\t\t\t\tclientId: \"https://client.example/cimd\",\n\t\t\t\t\tclientName: \"New\",\n\t\t\t\t\tscopes: [\"tools\"],\n\t\t\t\t\tcreatedAt: now - 10,\n\t\t\t\t},\n\t\t\t]);\n\t\t});\n\n\t\ttest(\"listGrants leaves out grants without a usable token\", async () => {\n\t\t\tawait store.put(record({ grantId: \"g_expired\", expiresAt: now }));\n\t\t\tawait store.put(\n\t\t\t\trecord({ grantId: \"g_used\", kind: \"refresh\", usedAt: now - 1 }),\n\t\t\t);\n\t\t\tawait store.put(\n\t\t\t\trecord({ grantId: \"g_live\", kind: \"refresh\", expiresAt: now + 1 }),\n\t\t\t);\n\t\t\tconst grants = await store.listGrants(\"addr-a\", now);\n\t\t\texpect(grants.map((g) => g.grantId)).toEqual([\"g_live\"]);\n\t\t});\n\n\t\ttest(\"listGrants of an unknown address is empty\", async () => {\n\t\t\texpect(await store.listGrants(\"nobody\", now)).toEqual([]);\n\t\t});\n\n\t\ttest(\"changing a returned record does not change the store\", async () => {\n\t\t\tconst r = record();\n\t\t\tawait store.put(r);\n\t\t\tconst got = await store.get(r.hash);\n\t\t\tif (got === undefined) throw new Error(\"missing\");\n\t\t\tgot.scopes.push(\"mutated\");\n\t\t\tgot.expiresAt = 0;\n\t\t\texpect(await store.get(r.hash)).toEqual(r);\n\t\t});\n\t});\n}\n"
+  ],
+  "mappings": ";;AAAA;AAYO,SAAS,qBAAqB,CACpC,MACA,SACO;AAAA,EACP,SAAS,2BAA2B,QAAQ,MAAM;AAAA,IACjD,IAAI;AAAA,IACJ,MAAM,MAAM;AAAA,IACZ,IAAI,MAAM;AAAA,IAEV,MAAM,QAAQ,EAAE,KAAK,WAAW,MAAM,SAAW;AAAA,IAEjD,MAAM,SAAS,CAAC,OAA6B,CAAC,MAAmB;AAAA,MAChE;AAAA,MACA,OAAO;AAAA,QACN,MAAM,QAAQ;AAAA,QACd,MAAM;AAAA,QACN,SAAS;AAAA,QACT,WAAW;AAAA,QACX,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,QAAQ,CAAC,OAAO;AAAA,QAChB,gBAAgB,MAAM;AAAA,QACtB,UAAU;AAAA,QACV,WAAW,MAAM;AAAA,WACd;AAAA,MACJ;AAAA;AAAA,IAGD,WAAW,YAAY;AAAA,MACtB,QAAQ,MAAM,QAAQ;AAAA,KACtB;AAAA,IAED,UAAU,YAAY;AAAA,MACrB,MAAM,MAAM,QAAQ;AAAA,KACpB;AAAA,IAED,KAAK,wCAAwC,YAAY;AAAA,MACxD,MAAM,IAAI,OAAO,EAAE,QAAQ,CAAC,SAAS,OAAO,EAAE,CAAC;AAAA,MAC/C,OAAO,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI;AAAA,MACpC,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AAAA,KACzC;AAAA,IAED,KAAK,uCAAuC,YAAY;AAAA,MACvD,OAAO,MAAM,MAAM,IAAI,MAAM,CAAC,EAAE,cAAc;AAAA,KAC9C;AAAA,IAED,KAAK,8CAA8C,YAAY;AAAA,MAC9D,MAAM,IAAI,OAAO;AAAA,MACjB,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,MAAM,MAAM,IAAI,KAAK,GAAG,YAAY,WAAW,WAAW,MAAM,EAAE,CAAC;AAAA,MACnE,MAAM,MAAM,MAAM,MAAM,IAAI,EAAE,IAAI;AAAA,MAClC,OAAO,KAAK,UAAU,EAAE,KAAK,SAAS;AAAA,MACtC,OAAO,KAAK,SAAS,EAAE,KAAK,MAAM,CAAC;AAAA,KACnC;AAAA,IAED,KAAK,kDAAkD,YAAY;AAAA,MAClE,MAAM,UAAU,OAAO,EAAE,WAAW,MAAM,EAAE,CAAC;AAAA,MAC7C,MAAM,OAAO,OAAO,EAAE,MAAM,WAAW,QAAQ,MAAM,GAAG,CAAC;AAAA,MACzD,MAAM,MAAM,IAAI,OAAO;AAAA,MACvB,MAAM,MAAM,IAAI,IAAI;AAAA,MACpB,OAAO,MAAM,MAAM,IAAI,QAAQ,IAAI,CAAC,EAAE,QAAQ,OAAO;AAAA,MACrD,OAAO,MAAM,MAAM,IAAI,KAAK,IAAI,CAAC,EAAE,QAAQ,IAAI;AAAA,KAC/C;AAAA,IAED,KAAK,sDAAsD,YAAY;AAAA,MACtE,MAAM,IAAI,OAAO;AAAA,MACjB,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,MAAM,MAAM,MAAM,MAAM,IAAI,EAAE,IAAI;AAAA,MAClC,OAAO,QAAQ,aAAa,YAAY,GAAG,EAAE,KAAK,KAAK;AAAA,KACvD;AAAA,IAED,KAAK,sCAAsC,YAAY;AAAA,MACtD,MAAM,IAAI,OAAO,EAAE,MAAM,UAAU,CAAC;AAAA,MACpC,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,OAAO,MAAM,MAAM,SAAS,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,KAAK,IAAI;AAAA,MACvD,OAAO,MAAM,MAAM,SAAS,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,KAAK,KAAK;AAAA,MACxD,QAAQ,MAAM,MAAM,IAAI,EAAE,IAAI,IAAI,MAAM,EAAE,KAAK,MAAM,CAAC;AAAA,KACtD;AAAA,IAED,KAAK,qCAAqC,YAAY;AAAA,MACrD,OAAO,MAAM,MAAM,SAAS,QAAQ,GAAG,CAAC,EAAE,KAAK,KAAK;AAAA,KACpD;AAAA,IAED,KAAK,+CAA+C,YAAY;AAAA,MAC/D,MAAM,IAAI,OAAO,EAAE,MAAM,UAAU,CAAC;AAAA,MACpC,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,MAAM,UAAU,MAAM,QAAQ,IAC7B,MAAM,KAAK,EAAE,QAAQ,GAAG,GAAG,CAAC,GAAG,MAAM,MAAM,SAAS,EAAE,MAAM,MAAM,CAAC,CAAC,CACrE;AAAA,MACA,OAAO,QAAQ,OAAO,OAAO,CAAC,EAAE,aAAa,CAAC;AAAA,KAC9C;AAAA,IAED,KAAK,oDAAoD,YAAY;AAAA,MACpE,MAAM,IAAI,OAAO,EAAE,SAAS,MAAM,CAAC;AAAA,MACnC,MAAM,KAAK,OAAO,EAAE,SAAS,OAAO,MAAM,UAAU,CAAC;AAAA,MACrD,MAAM,IAAI,OAAO,EAAE,SAAS,MAAM,CAAC;AAAA,MACnC,WAAW,KAAK,CAAC,GAAG,IAAI,CAAC;AAAA,QAAG,MAAM,MAAM,IAAI,CAAC;AAAA,MAC7C,OAAO,MAAM,MAAM,OAAO,EAAE,SAAS,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,CAAC;AAAA,MAC5D,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,cAAc;AAAA,MAC9C,OAAO,MAAM,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,cAAc;AAAA,MAC/C,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AAAA,KACzC;AAAA,IAED,KAAK,wDAAwD,YAAY;AAAA,MACxE,MAAM,IAAI,OAAO,EAAE,WAAW,UAAU,SAAS,MAAM,CAAC;AAAA,MACxD,MAAM,IAAI,OAAO,EAAE,WAAW,UAAU,SAAS,MAAM,CAAC;AAAA,MACxD,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,OAAO,MAAM,MAAM,OAAO,EAAE,WAAW,SAAS,GAAG,KAAK,CAAC,EAAE,KAAK,CAAC;AAAA,MACjE,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,cAAc;AAAA,MAC9C,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AAAA,KACzC;AAAA,IAED,KAAK,+BAA+B,YAAY;AAAA,MAC/C,OAAO,MAAM,MAAM,OAAO,EAAE,SAAS,OAAO,GAAG,KAAK,CAAC,EAAE,KAAK,CAAC;AAAA,KAC7D;AAAA,IAED,KAAK,kEAAkE,YAAY;AAAA,MAClF,MAAM,MAAM,OAAO,EAAE,SAAS,SAAS,GAAG,KAAK;AAAA,MAC/C,MAAM,OAAO,OAAO,EAAE,SAAS,UAAU,MAAM,UAAU,CAAC;AAAA,MAC1D,OAAO,MAAM,MAAM,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK;AAAA,MACxC,OAAO,MAAM,MAAM,IAAI,KAAK,IAAI,CAAC,EAAE,cAAc;AAAA,MACjD,OAAO,MAAM,MAAM,IAAI,OAAO,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI;AAAA,MACjE,MAAM,MAAM,cAAc,MAAM,SAAS;AAAA,MACzC,OAAO,MAAM,MAAM,IAAI,OAAO,EAAE,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI;AAAA,KAChE;AAAA,IAED,KAAK,iFAAiF,YAAY;AAAA,MACjG,MAAM,MAAM,OAAO,EAAE,WAAW,SAAS,GAAG,KAAK;AAAA,MACjD,OACC,MAAM,MAAM,IAAI,OAAO,EAAE,SAAS,YAAY,gBAAgB,IAAI,CAAC,CAAC,CACrE,EAAE,KAAK,KAAK;AAAA,MACZ,OACC,MAAM,MAAM,IACX,OAAO,EAAE,SAAS,WAAW,gBAAgB,MAAM,EAAE,CAAC,CACvD,CACD,EAAE,KAAK,IAAI;AAAA,MACX,OACC,MAAM,MAAM,IACX,OAAO;AAAA,QACN,SAAS;AAAA,QACT,WAAW;AAAA,QACX,gBAAgB;AAAA,MACjB,CAAC,CACF,CACD,EAAE,KAAK,IAAI;AAAA,KACX;AAAA,IAED,KAAK,4DAA4D,YAAY;AAAA,MAC5E,SAAS,IAAI,EAAG,IAAI,IAAI,KAAK;AAAA,QAC5B,MAAM,IAAI,OAAO,EAAE,SAAS,UAAU,KAAK,MAAM,UAAU,CAAC;AAAA,QAC5D,MAAM,QAAQ,IAAI;AAAA,UACjB,MAAM,IAAI,CAAC;AAAA,UACX,MAAM,OAAO,EAAE,SAAS,EAAE,QAAQ,GAAG,KAAK;AAAA,QAC3C,CAAC;AAAA,QACD,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,cAAc;AAAA,MAC/C;AAAA,KACA;AAAA,IAED,KAAK,4DAA4D,YAAY;AAAA,MAC5E,MAAM,OAAO,OAAO,EAAE,WAAW,MAAM,EAAE,CAAC;AAAA,MAC1C,MAAM,OAAO,OAAO,EAAE,WAAW,IAAI,CAAC;AAAA,MACtC,MAAM,OAAO,OAAO,EAAE,WAAW,MAAM,EAAE,CAAC;AAAA,MAC1C,WAAW,KAAK,CAAC,MAAM,MAAM,IAAI;AAAA,QAAG,MAAM,MAAM,IAAI,CAAC;AAAA,MACrD,OAAO,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,KAAK,CAAC;AAAA,MAC7C,OAAO,MAAM,MAAM,IAAI,KAAK,IAAI,CAAC,EAAE,cAAc;AAAA,MACjD,OAAO,MAAM,MAAM,IAAI,KAAK,IAAI,CAAC,EAAE,cAAc;AAAA,MACjD,OAAO,MAAM,MAAM,IAAI,KAAK,IAAI,CAAC,EAAE,QAAQ,IAAI;AAAA,KAC/C;AAAA,IAED,KAAK,yDAAyD,YAAY;AAAA,MACzE,MAAM,MAAM,IACX,OAAO;AAAA,QACN,SAAS;AAAA,QACT,gBAAgB,MAAM;AAAA,QACtB,YAAY;AAAA,MACb,CAAC,CACF;AAAA,MACA,MAAM,MAAM,IACX,OAAO;AAAA,QACN,SAAS;AAAA,QACT,gBAAgB,MAAM;AAAA,QACtB,YAAY;AAAA,QACZ,QAAQ,CAAC,OAAO;AAAA,MACjB,CAAC,CACF;AAAA,MACA,MAAM,MAAM,IACX,OAAO;AAAA,QACN,SAAS;AAAA,QACT,MAAM;AAAA,QACN,gBAAgB,MAAM;AAAA,QACtB,YAAY;AAAA,MACb,CAAC,CACF;AAAA,MACA,MAAM,MAAM,IAAI,OAAO,EAAE,SAAS,WAAW,WAAW,SAAS,CAAC,CAAC;AAAA,MACnE,OAAO,MAAM,MAAM,WAAW,UAAU,GAAG,CAAC,EAAE,QAAQ;AAAA,QACrD;AAAA,UACC,SAAS;AAAA,UACT,UAAU;AAAA,UACV,YAAY;AAAA,UACZ,QAAQ,CAAC,OAAO;AAAA,UAChB,WAAW,MAAM;AAAA,QAClB;AAAA,QACA;AAAA,UACC,SAAS;AAAA,UACT,UAAU;AAAA,UACV,YAAY;AAAA,UACZ,QAAQ,CAAC,OAAO;AAAA,UAChB,WAAW,MAAM;AAAA,QAClB;AAAA,MACD,CAAC;AAAA,KACD;AAAA,IAED,KAAK,uDAAuD,YAAY;AAAA,MACvE,MAAM,MAAM,IAAI,OAAO,EAAE,SAAS,aAAa,WAAW,IAAI,CAAC,CAAC;AAAA,MAChE,MAAM,MAAM,IACX,OAAO,EAAE,SAAS,UAAU,MAAM,WAAW,QAAQ,MAAM,EAAE,CAAC,CAC/D;AAAA,MACA,MAAM,MAAM,IACX,OAAO,EAAE,SAAS,UAAU,MAAM,WAAW,WAAW,MAAM,EAAE,CAAC,CAClE;AAAA,MACA,MAAM,SAAS,MAAM,MAAM,WAAW,UAAU,GAAG;AAAA,MACnD,OAAO,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;AAAA,KACvD;AAAA,IAED,KAAK,6CAA6C,YAAY;AAAA,MAC7D,OAAO,MAAM,MAAM,WAAW,UAAU,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AAAA,KACxD;AAAA,IAED,KAAK,wDAAwD,YAAY;AAAA,MACxE,MAAM,IAAI,OAAO;AAAA,MACjB,MAAM,MAAM,IAAI,CAAC;AAAA,MACjB,MAAM,MAAM,MAAM,MAAM,IAAI,EAAE,IAAI;AAAA,MAClC,IAAI,QAAQ;AAAA,QAAW,MAAM,IAAI,MAAM,SAAS;AAAA,MAChD,IAAI,OAAO,KAAK,SAAS;AAAA,MACzB,IAAI,YAAY;AAAA,MAChB,OAAO,MAAM,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AAAA,KACzC;AAAA,GACD;AAAA;",
+  "debugId": "894AE659D8460D9664756E2164756E21",
+  "names": []
+}

package/tokens.d.ts

@@ -0,0 +1,45 @@
+import type { TokenKind, TokenRecord, TokenStore } from "./store/types.js";
+/** A new opaque token with 256 bits of randomness. */
+export declare function newToken(kind: TokenKind): string;
+/** A random identifier with a readable prefix, e.g. `g_…`, `s_…`. */
+export declare function newId(prefix: string): string;
+/** SHA-256 of a token, base64url without padding: the store key. */
+export declare function hashToken(token: string): string;
+/** The parts of a grant needed to issue tokens for it. */
+export interface GrantInput {
+    grantId?: string;
+    addressId: string;
+    clientId: string;
+    clientName: string;
+    scopes?: string[];
+    grantCreatedAt?: number;
+}
+/**
+ * Issue an access token for a grant and store its hash, without OAuth. An
+ * internal helper for tests that need a token but not the flow; the token
+ * endpoint issues through `issueTokenPair`.
+ */
+export declare function issueAccessToken(store: TokenStore, grant: GrantInput, options: {
+    ttlMs: number;
+    now?: number;
+}): Promise<{
+    token: string;
+    record: TokenRecord;
+}>;
+/**
+ * A new access token and refresh token for a grant (DEC-029). Neither lives
+ * beyond `grantEndsAt` (DEC-062). Returns `undefined` if the store refuses
+ * them because the grant was revoked meanwhile (its tombstone, DEC-063).
+ */
+export declare function issueTokenPair(store: TokenStore, grant: Required<Omit<GrantInput, "scopes">> & {
+    scopes: string[];
+}, options: {
+    accessTtlMs: number;
+    refreshTtlMs: number;
+    grantEndsAt: number;
+    now?: number;
+}): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+} | undefined>;

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.