@stonyx/oauth 0.1.1-alpha.33 → 0.1.1-alpha.34

package/README.md

@@ -257,7 +257,7 @@ What the fragment does **not** remove is browser history and readability by page
 | Entropy | 32 random bytes, base64url | Independent of the session id, never derived from it. |
 | Authenticates | **nothing** | `GET /auth` validates against the session store, which has never heard of the ticket. A ticket in a `session-id` header is a `401`. |
 | Failure modes | one indistinguishable `400` | Unknown, spent, expired and unparseable are not told apart. |
-| Server-side storage | **SHA-256 digest only** | The store is keyed by the digest of the ticket, never by the ticket, so a heap dump or an accidental log of the map yields a useless digest rather than a live redeemable credential. Same discipline as the `oauth_state` binding, which stores `bindingHash` and never the binding value. No constant-time compare is needed: lookup is a hash probe on a 256-bit key, not a secret-dependent byte comparison. |
+| Server-side storage | **keyed by the ticket digest** | The store is keyed by the SHA-256 of the ticket, never by the ticket, so the map holds no redeemable *ticket*: a reader of the map gets a digest, and a digest cannot be presented to the exchange. **It does still hold the live `sessionId` in plaintext, in the record value**, so the map is sensitive and must not be dumped or logged. Note this is the mirror image of the `oauth_state` binding rather than the same shape: `pendingStates` is keyed by the plaintext state and keeps the digest (`bindingHash`) in the value, so that record unlocks nothing on its own; here the digest is the key and the value is a live credential. Both share the discipline of never storing the client-presented secret in the clear. No constant-time compare is needed: lookup is a hash probe on a 256-bit key, not a secret-dependent byte comparison. |
 | Exchange response | `Cache-Control: no-store` | The `200` body is the session id. A `POST` is not cacheable without explicit freshness, so this is defence in depth — no intermediary or service worker retains the credential. |
 
 ### Known residual risk

package/dist/ticket-store.d.ts

@@ -78,11 +78,26 @@ export default class TicketStore {
     /**
      * Live tickets, keyed by the **SHA-256 of the ticket**, never by the ticket.
      *
-     * Same discipline as `OAuth.pendingStates`, which holds `bindingHash` and
-     * never the binding value: a ticket is a client-presented secret looked up
-     * server-side, so a heap dump, a debug serialisation or an accidental log of
-     * this map should yield a useless digest rather than a live redeemable
-     * credential. The two secret stores in this module now agree.
+     * Keying by the digest means the map holds no redeemable *ticket*: a ticket
+     * is a client-presented secret looked up server-side, so what a reader of
+     * this map gets is a digest, and a digest cannot be presented to `redeem`.
+     *
+     * That does not make the map safe to expose. The record *value* holds a
+     * plaintext, live `sessionId` — the 24-hour bearer credential this store
+     * exists to keep out of URLs — so a heap dump, a debug serialisation or an
+     * accidental log of this map yields live session ids. The map is sensitive
+     * on that basis and must not be dumped or logged. Whether the stored
+     * `sessionId` should itself be protected is a separate question, and is not
+     * settled here.
+     *
+     * This is the mirror image of `OAuth.pendingStates`, not the same shape:
+     * there the *key* is the plaintext state token and the digest
+     * (`bindingHash`) sits in the value, so that record unlocks nothing on its
+     * own; here the digest is the key and the value is a live credential. What
+     * the two stores share is the discipline of never keeping a
+     * client-presented secret in the clear — neither the ticket nor the binding
+     * value is on the heap — but they place the digest on opposite sides of the
+     * entry.
      *
      * No constant-time comparison is needed and none is used: lookup is a hash
      * probe on a 256-bit high-entropy key, not a secret-dependent byte
@@ -91,7 +106,7 @@ export default class TicketStore {
      */
     tickets: Map<string, TicketRecord>;
     ttl: number;
-    /** SHA-256 of a ticket, hex — the only form this store keeps on the heap. */
+    /** SHA-256 of a ticket, hex — the only form of the *ticket* this store keeps. */
     static hash(ticket: string): string;
     /**
      * Mints a ticket for a freshly created session.

package/dist/ticket-store.js

@@ -70,11 +70,26 @@ export default class TicketStore {
     /**
      * Live tickets, keyed by the **SHA-256 of the ticket**, never by the ticket.
      *
-     * Same discipline as `OAuth.pendingStates`, which holds `bindingHash` and
-     * never the binding value: a ticket is a client-presented secret looked up
-     * server-side, so a heap dump, a debug serialisation or an accidental log of
-     * this map should yield a useless digest rather than a live redeemable
-     * credential. The two secret stores in this module now agree.
+     * Keying by the digest means the map holds no redeemable *ticket*: a ticket
+     * is a client-presented secret looked up server-side, so what a reader of
+     * this map gets is a digest, and a digest cannot be presented to `redeem`.
+     *
+     * That does not make the map safe to expose. The record *value* holds a
+     * plaintext, live `sessionId` — the 24-hour bearer credential this store
+     * exists to keep out of URLs — so a heap dump, a debug serialisation or an
+     * accidental log of this map yields live session ids. The map is sensitive
+     * on that basis and must not be dumped or logged. Whether the stored
+     * `sessionId` should itself be protected is a separate question, and is not
+     * settled here.
+     *
+     * This is the mirror image of `OAuth.pendingStates`, not the same shape:
+     * there the *key* is the plaintext state token and the digest
+     * (`bindingHash`) sits in the value, so that record unlocks nothing on its
+     * own; here the digest is the key and the value is a live credential. What
+     * the two stores share is the discipline of never keeping a
+     * client-presented secret in the clear — neither the ticket nor the binding
+     * value is on the heap — but they place the digest on opposite sides of the
+     * entry.
      *
      * No constant-time comparison is needed and none is used: lookup is a hash
      * probe on a 256-bit high-entropy key, not a secret-dependent byte
@@ -83,7 +98,7 @@ export default class TicketStore {
      */
     tickets = new Map();
     ttl = TICKET_TTL_MS;
-    /** SHA-256 of a ticket, hex — the only form this store keeps on the heap. */
+    /** SHA-256 of a ticket, hex — the only form of the *ticket* this store keeps. */
     static hash(ticket) {
         return createHash('sha256').update(ticket).digest('hex');
     }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.33",
+  "version": "0.1.1-alpha.34",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",

package/src/ticket-store.ts

@@ -84,11 +84,26 @@ export default class TicketStore {
   /**
    * Live tickets, keyed by the **SHA-256 of the ticket**, never by the ticket.
    *
-   * Same discipline as `OAuth.pendingStates`, which holds `bindingHash` and
-   * never the binding value: a ticket is a client-presented secret looked up
-   * server-side, so a heap dump, a debug serialisation or an accidental log of
-   * this map should yield a useless digest rather than a live redeemable
-   * credential. The two secret stores in this module now agree.
+   * Keying by the digest means the map holds no redeemable *ticket*: a ticket
+   * is a client-presented secret looked up server-side, so what a reader of
+   * this map gets is a digest, and a digest cannot be presented to `redeem`.
+   *
+   * That does not make the map safe to expose. The record *value* holds a
+   * plaintext, live `sessionId` — the 24-hour bearer credential this store
+   * exists to keep out of URLs — so a heap dump, a debug serialisation or an
+   * accidental log of this map yields live session ids. The map is sensitive
+   * on that basis and must not be dumped or logged. Whether the stored
+   * `sessionId` should itself be protected is a separate question, and is not
+   * settled here.
+   *
+   * This is the mirror image of `OAuth.pendingStates`, not the same shape:
+   * there the *key* is the plaintext state token and the digest
+   * (`bindingHash`) sits in the value, so that record unlocks nothing on its
+   * own; here the digest is the key and the value is a live credential. What
+   * the two stores share is the discipline of never keeping a
+   * client-presented secret in the clear — neither the ticket nor the binding
+   * value is on the heap — but they place the digest on opposite sides of the
+   * entry.
    *
    * No constant-time comparison is needed and none is used: lookup is a hash
    * probe on a 256-bit high-entropy key, not a secret-dependent byte
@@ -98,7 +113,7 @@ export default class TicketStore {
   tickets = new Map<string, TicketRecord>();
   ttl = TICKET_TTL_MS;
 
-  /** SHA-256 of a ticket, hex — the only form this store keeps on the heap. */
+  /** SHA-256 of a ticket, hex — the only form of the *ticket* this store keeps. */
   static hash(ticket: string): string {
     return createHash('sha256').update(ticket).digest('hex');
   }