@shipstatic/types 2.7.0 → 2.8.0-beta.2

package/dist/index.d.ts

@@ -1118,6 +1118,39 @@ export declare const DEPLOY_TOKEN: {
     /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
     readonly TOTAL_LENGTH: 39;
 };
+/**
+ * Shape constants for OAuth access tokens (`oauth-{32 hex chars}`) — the
+ * delegated population, minted by the platform's own authorization server
+ * for a connected app acting on a user's behalf.
+ *
+ * Same width as the other two, and for the same reason: one entropy standard
+ * across the platform, so "how long is a credential" has one answer.
+ *
+ * **This population is the access token alone.** Refresh tokens, authorization
+ * codes and client secrets are deliberately NOT here and are deliberately not
+ * prefixed by this constant: none of them ever enters the `Authorization:
+ * Bearer` slot — a refresh token is posted as a form field to the token
+ * endpoint, which knows what it is receiving — so `classifyToken` never sees
+ * one and a prefix would name a population no dispatcher dispatches. The same
+ * reasoning that keeps the deployment claim code bare.
+ *
+ * **The prefix must be applied at the MINT, never as a display wrapper.** The
+ * authorization server hashes what it stores and the API hashes what it is
+ * presented, so the prefix has to be inside the hashed string on both sides.
+ * `@better-auth/oauth-provider` offers a `prefix.opaqueAccessToken` option
+ * that prepends AFTER hashing and strips on its own read paths; using it would
+ * store a hash of the UNPREFIXED token and silently break the platform's read
+ * arm. The API therefore mints through `generateOpaqueAccessToken` — recorded
+ * beside the config in `cloudflare/api/src/lib/auth/instance.ts`.
+ */
+export declare const OAUTH_TOKEN: {
+    /** Prefix that identifies an OAuth access token. */
+    readonly PREFIX: "oauth-";
+    /** Number of hex characters following the prefix. */
+    readonly HEX_LENGTH: 32;
+    /** Total length including prefix (`PREFIX.length + HEX_LENGTH = 38`). */
+    readonly TOTAL_LENGTH: 38;
+};
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity
  * header — rate-limit bucketing for multi-tenant orchestrators). The API
@@ -1138,16 +1171,23 @@ export declare const CALLER: {
  * client token in one wire slot (`Authorization: Bearer <value>`) and
  * classifies by value, never by a side channel — this is the classifier.
  *
- * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
- * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
- * straight into an auth method and the pair can never drift. `OPAQUE` is any
- * other value — shape says nothing about it, so only a lookup can. Today the
- * server refuses every opaque bearer; the OAuth access-token population
- * resolves there when the authorization server ships.
+ * `API_KEY`, `DEPLOY_TOKEN` and `OAUTH` *are* `AuthMethod.API_KEY`,
+ * `AuthMethod.TOKEN` and `AuthMethod.OAUTH` — the equality is structural, so
+ * a classification flows straight into an auth method and the trio can never
+ * drift.
+ *
+ * `OPAQUE` is any other value, and since 2026-08-14 it names NO population:
+ * every credential this platform mints for the Bearer slot carries a prefix,
+ * so an opaque bearer is a bearer we did not mint. It stays a member rather
+ * than becoming a `null` return because a dispatcher with a total codomain
+ * reads better than one with an absence in it — and because it is where a
+ * future population would land before anyone gave it a shape, which is
+ * exactly what the OAuth token itself did until its prefix existed.
  */
 export declare const TokenKind: {
     readonly API_KEY: "apiKey";
     readonly DEPLOY_TOKEN: "token";
+    readonly OAUTH: "oauth";
     readonly OPAQUE: "opaque";
 };
 export type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
@@ -1158,6 +1198,43 @@ export type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
  * is what guarantees client and server can never disagree on dispatch.
  */
 export declare function classifyToken(token: string): TokenKindType;
+/**
+ * Read the credential out of an `Authorization` header value — the step
+ * BEFORE `classifyToken`, and the other half of the one wire slot this
+ * section owns.
+ *
+ * Returns the credential's own bytes, or `null` when the header carries a
+ * foreign scheme or nothing after the scheme.
+ *
+ * **The scheme is folded; the credential is not.** RFC 7235 §2.1 makes the
+ * auth-scheme case-insensitive, so `bearer`, `Bearer` and `BEARER` are the
+ * same header. The value after it is opaque and is compared literally
+ * everywhere it is used — `ship-`/`deploy-`/`oauth-` are lowercase hex, and
+ * folding them would make a credential match values it is not.
+ *
+ * **This platform has paid for the rule twice, which is why it has an owner
+ * rather than a convention.** A spec-conformant `bearer ship-…` client was
+ * refused for as long as the API's scheme test was spelled case-sensitively;
+ * and `@better-auth/oauth-provider` carries the same defect in four places
+ * today (`startsWith("Bearer ")`), which is precisely why the platform folds
+ * the scheme itself and hands the provider a bare token.
+ *
+ * **ABSENCE is deliberately not this function's business.** A missing header
+ * and an unreadable one are different facts, and the callers that care split
+ * on them: the API worker's middleware distinguishes `absent` (the only
+ * anonymous path) from `unreadable` (a presented credential that is refused),
+ * and collapsing the two here would take that distinction away from the layer
+ * that needs it. Callers check for the header themselves and pass its value.
+ *
+ * **Why this lives in the constitution rather than in a worker's `shared/`.**
+ * It is the same wire boundary `classifyToken` already owns — one reads the
+ * slot, the other dispatches on what came out — and a rule with two holders
+ * whose drift is silent earns exactly one owner regardless of what the
+ * convoy costs. The estate's recorded refusal to own a `Bearer` CONSTANT
+ * stands and is a different thing: that is RFC vocabulary, the same reason
+ * this package owns no `"POST"`. A parser is not a spelling.
+ */
+export declare function readBearerValue(header: string): string | null;
 /**
  * OAuth scope vocabulary for delegated third-party access tokens.
  * Single source of truth used by the authorization server (advertised in
@@ -1243,11 +1320,22 @@ export declare function validateApiKey(apiKey: string): void;
  * Validate deploy token format
  */
 export declare function validateDeployToken(deployToken: string): void;
+/**
+ * Validate OAuth access token format
+ */
+export declare function validateOAuthToken(oauthToken: string): void;
 /**
  * Validate a client token of any population. Classifies by shape and applies
- * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
- * validated strictly; opaque tokens (OAuth access tokens, future populations)
- * only need to be non-empty — their validity is the server's to decide.
+ * the matching format rules: all three prefixed populations are validated
+ * strictly; an OPAQUE token only needs to be non-empty.
+ *
+ * **The OPAQUE arm stays permissive on purpose**, even though the platform no
+ * longer mints an unprefixed credential. It is the fallback for a population
+ * that does not exist yet, and a client refusing a shape the server would
+ * accept is the one failure mode this boundary must never have — the server
+ * decides, and it refuses an unrecognised bearer anyway. Unprefixed OAuth
+ * tokens from before 2026-08-14 land here and are refused server-side, which
+ * is correct: they were revoked by the change, not grandfathered.
  */
 export declare function validateToken(token: string): void;
 /**

package/dist/index.js

@@ -1015,12 +1015,13 @@ export function hasUnbuiltMarker(filePath) {
 // =============================================================================
 // The one address for credential vocabulary: where human identity lives
 // (AUTH_BASE_PATH), how a request is authorized (AuthMethod), the shapes
-// that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN, CALLER),
-// the single dispatch over them (TokenKind, classifyToken), and the
-// delegated-access scopes (OAuthScope).
+// that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN,
+// OAUTH_TOKEN, CALLER), the two halves of the one Bearer slot
+// (readBearerValue reads it, classifyToken/TokenKind dispatch on what came
+// out), and the delegated-access scopes (OAuthScope).
 //
 // THE SHAPE LAW, in three clauses, over the `Authorization: Bearer` slot's
-// two populations below. The deployment claim code is the API's own
+// three populations below. The deployment claim code is the API's own
 // (`AUTH.CLAIM`, server-side: the API mints it and the API validates it, so
 // it has one holder and stays there) and shares only clause 1 — it is the
 // platform's one deliberately BARE secret, because it never enters the
@@ -1037,9 +1038,12 @@ export function hasUnbuiltMarker(filePath) {
 //
 //  2. EVERY BEARER POPULATION IS NAMED BY ITS PREFIX. A credential says what
 //     it is before anything parses it — which is what lets `classifyToken`
-//     below dispatch two populations sharing one `Authorization: Bearer`
+//     below dispatch three populations sharing one `Authorization: Bearer`
 //     slot, and what lets a value found in a log, a support ticket or a
-//     pasted URL be recognised and revoked on sight.
+//     pasted URL be recognised and revoked on sight. The OAuth access token
+//     was this clause's one standing exception until 2026-08-14 — the
+//     authorization server it was born on had no mint hook to give it a
+//     prefix, and its successor does.
 //
 //  3. NO PREFIX IS A PREFIX OF ANOTHER. This is what makes the dispatch
 //     order-independent, and it is the reason the populations are named on
@@ -1104,6 +1108,39 @@ export const DEPLOY_TOKEN = {
     /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
     TOTAL_LENGTH: 39,
 };
+/**
+ * Shape constants for OAuth access tokens (`oauth-{32 hex chars}`) — the
+ * delegated population, minted by the platform's own authorization server
+ * for a connected app acting on a user's behalf.
+ *
+ * Same width as the other two, and for the same reason: one entropy standard
+ * across the platform, so "how long is a credential" has one answer.
+ *
+ * **This population is the access token alone.** Refresh tokens, authorization
+ * codes and client secrets are deliberately NOT here and are deliberately not
+ * prefixed by this constant: none of them ever enters the `Authorization:
+ * Bearer` slot — a refresh token is posted as a form field to the token
+ * endpoint, which knows what it is receiving — so `classifyToken` never sees
+ * one and a prefix would name a population no dispatcher dispatches. The same
+ * reasoning that keeps the deployment claim code bare.
+ *
+ * **The prefix must be applied at the MINT, never as a display wrapper.** The
+ * authorization server hashes what it stores and the API hashes what it is
+ * presented, so the prefix has to be inside the hashed string on both sides.
+ * `@better-auth/oauth-provider` offers a `prefix.opaqueAccessToken` option
+ * that prepends AFTER hashing and strips on its own read paths; using it would
+ * store a hash of the UNPREFIXED token and silently break the platform's read
+ * arm. The API therefore mints through `generateOpaqueAccessToken` — recorded
+ * beside the config in `cloudflare/api/src/lib/auth/instance.ts`.
+ */
+export const OAUTH_TOKEN = {
+    /** Prefix that identifies an OAuth access token. */
+    PREFIX: 'oauth-',
+    /** Number of hex characters following the prefix. */
+    HEX_LENGTH: 32,
+    /** Total length including prefix (`PREFIX.length + HEX_LENGTH = 38`). */
+    TOTAL_LENGTH: 38,
+};
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity
  * header — rate-limit bucketing for multi-tenant orchestrators). The API
@@ -1124,16 +1161,23 @@ export const CALLER = {
  * client token in one wire slot (`Authorization: Bearer <value>`) and
  * classifies by value, never by a side channel — this is the classifier.
  *
- * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
- * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
- * straight into an auth method and the pair can never drift. `OPAQUE` is any
- * other value — shape says nothing about it, so only a lookup can. Today the
- * server refuses every opaque bearer; the OAuth access-token population
- * resolves there when the authorization server ships.
+ * `API_KEY`, `DEPLOY_TOKEN` and `OAUTH` *are* `AuthMethod.API_KEY`,
+ * `AuthMethod.TOKEN` and `AuthMethod.OAUTH` — the equality is structural, so
+ * a classification flows straight into an auth method and the trio can never
+ * drift.
+ *
+ * `OPAQUE` is any other value, and since 2026-08-14 it names NO population:
+ * every credential this platform mints for the Bearer slot carries a prefix,
+ * so an opaque bearer is a bearer we did not mint. It stays a member rather
+ * than becoming a `null` return because a dispatcher with a total codomain
+ * reads better than one with an absence in it — and because it is where a
+ * future population would land before anyone gave it a shape, which is
+ * exactly what the OAuth token itself did until its prefix existed.
  */
 export const TokenKind = {
     API_KEY: AuthMethod.API_KEY,
     DEPLOY_TOKEN: AuthMethod.TOKEN,
+    OAUTH: AuthMethod.OAUTH,
     OPAQUE: 'opaque',
 };
 /**
@@ -1147,8 +1191,53 @@ export function classifyToken(token) {
         return TokenKind.API_KEY;
     if (token.startsWith(DEPLOY_TOKEN.PREFIX))
         return TokenKind.DEPLOY_TOKEN;
+    if (token.startsWith(OAUTH_TOKEN.PREFIX))
+        return TokenKind.OAUTH;
     return TokenKind.OPAQUE;
 }
+/** The auth-scheme, lowercased — the form the comparison is made in. */
+const BEARER_SCHEME = 'bearer ';
+/**
+ * Read the credential out of an `Authorization` header value — the step
+ * BEFORE `classifyToken`, and the other half of the one wire slot this
+ * section owns.
+ *
+ * Returns the credential's own bytes, or `null` when the header carries a
+ * foreign scheme or nothing after the scheme.
+ *
+ * **The scheme is folded; the credential is not.** RFC 7235 §2.1 makes the
+ * auth-scheme case-insensitive, so `bearer`, `Bearer` and `BEARER` are the
+ * same header. The value after it is opaque and is compared literally
+ * everywhere it is used — `ship-`/`deploy-`/`oauth-` are lowercase hex, and
+ * folding them would make a credential match values it is not.
+ *
+ * **This platform has paid for the rule twice, which is why it has an owner
+ * rather than a convention.** A spec-conformant `bearer ship-…` client was
+ * refused for as long as the API's scheme test was spelled case-sensitively;
+ * and `@better-auth/oauth-provider` carries the same defect in four places
+ * today (`startsWith("Bearer ")`), which is precisely why the platform folds
+ * the scheme itself and hands the provider a bare token.
+ *
+ * **ABSENCE is deliberately not this function's business.** A missing header
+ * and an unreadable one are different facts, and the callers that care split
+ * on them: the API worker's middleware distinguishes `absent` (the only
+ * anonymous path) from `unreadable` (a presented credential that is refused),
+ * and collapsing the two here would take that distinction away from the layer
+ * that needs it. Callers check for the header themselves and pass its value.
+ *
+ * **Why this lives in the constitution rather than in a worker's `shared/`.**
+ * It is the same wire boundary `classifyToken` already owns — one reads the
+ * slot, the other dispatches on what came out — and a rule with two holders
+ * whose drift is silent earns exactly one owner regardless of what the
+ * convoy costs. The estate's recorded refusal to own a `Bearer` CONSTANT
+ * stands and is a different thing: that is RFC vocabulary, the same reason
+ * this package owns no `"POST"`. A parser is not a spelling.
+ */
+export function readBearerValue(header) {
+    if (header.slice(0, BEARER_SCHEME.length).toLowerCase() !== BEARER_SCHEME)
+        return null;
+    return header.slice(BEARER_SCHEME.length) || null;
+}
 /**
  * OAuth scope vocabulary for delegated third-party access tokens.
  * Single source of truth used by the authorization server (advertised in
@@ -1273,11 +1362,24 @@ export function validateApiKey(apiKey) {
 export function validateDeployToken(deployToken) {
     validatePrefixedCredential(deployToken, DEPLOY_TOKEN, 'Deploy token');
 }
+/**
+ * Validate OAuth access token format
+ */
+export function validateOAuthToken(oauthToken) {
+    validatePrefixedCredential(oauthToken, OAUTH_TOKEN, 'OAuth access token');
+}
 /**
  * Validate a client token of any population. Classifies by shape and applies
- * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
- * validated strictly; opaque tokens (OAuth access tokens, future populations)
- * only need to be non-empty — their validity is the server's to decide.
+ * the matching format rules: all three prefixed populations are validated
+ * strictly; an OPAQUE token only needs to be non-empty.
+ *
+ * **The OPAQUE arm stays permissive on purpose**, even though the platform no
+ * longer mints an unprefixed credential. It is the fallback for a population
+ * that does not exist yet, and a client refusing a shape the server would
+ * accept is the one failure mode this boundary must never have — the server
+ * decides, and it refuses an unrecognised bearer anyway. Unprefixed OAuth
+ * tokens from before 2026-08-14 land here and are refused server-side, which
+ * is correct: they were revoked by the change, not grandfathered.
  */
 export function validateToken(token) {
     switch (classifyToken(token)) {
@@ -1287,6 +1389,9 @@ export function validateToken(token) {
         case TokenKind.DEPLOY_TOKEN:
             validateDeployToken(token);
             return;
+        case TokenKind.OAUTH:
+            validateOAuthToken(token);
+            return;
         case TokenKind.OPAQUE:
             if (!token)
                 throw ShipError.validation('Token must be a non-empty string');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.7.0",
+  "version": "2.8.0-beta.2",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -1697,12 +1697,13 @@ export interface PingResponse {
 // =============================================================================
 // The one address for credential vocabulary: where human identity lives
 // (AUTH_BASE_PATH), how a request is authorized (AuthMethod), the shapes
-// that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN, CALLER),
-// the single dispatch over them (TokenKind, classifyToken), and the
-// delegated-access scopes (OAuthScope).
+// that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN,
+// OAUTH_TOKEN, CALLER), the two halves of the one Bearer slot
+// (readBearerValue reads it, classifyToken/TokenKind dispatch on what came
+// out), and the delegated-access scopes (OAuthScope).
 //
 // THE SHAPE LAW, in three clauses, over the `Authorization: Bearer` slot's
-// two populations below. The deployment claim code is the API's own
+// three populations below. The deployment claim code is the API's own
 // (`AUTH.CLAIM`, server-side: the API mints it and the API validates it, so
 // it has one holder and stays there) and shares only clause 1 — it is the
 // platform's one deliberately BARE secret, because it never enters the
@@ -1719,9 +1720,12 @@ export interface PingResponse {
 //
 //  2. EVERY BEARER POPULATION IS NAMED BY ITS PREFIX. A credential says what
 //     it is before anything parses it — which is what lets `classifyToken`
-//     below dispatch two populations sharing one `Authorization: Bearer`
+//     below dispatch three populations sharing one `Authorization: Bearer`
 //     slot, and what lets a value found in a log, a support ticket or a
-//     pasted URL be recognised and revoked on sight.
+//     pasted URL be recognised and revoked on sight. The OAuth access token
+//     was this clause's one standing exception until 2026-08-14 — the
+//     authorization server it was born on had no mint hook to give it a
+//     prefix, and its successor does.
 //
 //  3. NO PREFIX IS A PREFIX OF ANOTHER. This is what makes the dispatch
 //     order-independent, and it is the reason the populations are named on
@@ -1793,6 +1797,40 @@ export const DEPLOY_TOKEN = {
   TOTAL_LENGTH: 39,
 } as const;
 
+/**
+ * Shape constants for OAuth access tokens (`oauth-{32 hex chars}`) — the
+ * delegated population, minted by the platform's own authorization server
+ * for a connected app acting on a user's behalf.
+ *
+ * Same width as the other two, and for the same reason: one entropy standard
+ * across the platform, so "how long is a credential" has one answer.
+ *
+ * **This population is the access token alone.** Refresh tokens, authorization
+ * codes and client secrets are deliberately NOT here and are deliberately not
+ * prefixed by this constant: none of them ever enters the `Authorization:
+ * Bearer` slot — a refresh token is posted as a form field to the token
+ * endpoint, which knows what it is receiving — so `classifyToken` never sees
+ * one and a prefix would name a population no dispatcher dispatches. The same
+ * reasoning that keeps the deployment claim code bare.
+ *
+ * **The prefix must be applied at the MINT, never as a display wrapper.** The
+ * authorization server hashes what it stores and the API hashes what it is
+ * presented, so the prefix has to be inside the hashed string on both sides.
+ * `@better-auth/oauth-provider` offers a `prefix.opaqueAccessToken` option
+ * that prepends AFTER hashing and strips on its own read paths; using it would
+ * store a hash of the UNPREFIXED token and silently break the platform's read
+ * arm. The API therefore mints through `generateOpaqueAccessToken` — recorded
+ * beside the config in `cloudflare/api/src/lib/auth/instance.ts`.
+ */
+export const OAUTH_TOKEN = {
+  /** Prefix that identifies an OAuth access token. */
+  PREFIX: 'oauth-',
+  /** Number of hex characters following the prefix. */
+  HEX_LENGTH: 32,
+  /** Total length including prefix (`PREFIX.length + HEX_LENGTH = 38`). */
+  TOTAL_LENGTH: 38,
+} as const;
+
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity
  * header — rate-limit bucketing for multi-tenant orchestrators). The API
@@ -1814,16 +1852,23 @@ export const CALLER = {
  * client token in one wire slot (`Authorization: Bearer <value>`) and
  * classifies by value, never by a side channel — this is the classifier.
  *
- * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
- * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
- * straight into an auth method and the pair can never drift. `OPAQUE` is any
- * other value — shape says nothing about it, so only a lookup can. Today the
- * server refuses every opaque bearer; the OAuth access-token population
- * resolves there when the authorization server ships.
+ * `API_KEY`, `DEPLOY_TOKEN` and `OAUTH` *are* `AuthMethod.API_KEY`,
+ * `AuthMethod.TOKEN` and `AuthMethod.OAUTH` — the equality is structural, so
+ * a classification flows straight into an auth method and the trio can never
+ * drift.
+ *
+ * `OPAQUE` is any other value, and since 2026-08-14 it names NO population:
+ * every credential this platform mints for the Bearer slot carries a prefix,
+ * so an opaque bearer is a bearer we did not mint. It stays a member rather
+ * than becoming a `null` return because a dispatcher with a total codomain
+ * reads better than one with an absence in it — and because it is where a
+ * future population would land before anyone gave it a shape, which is
+ * exactly what the OAuth token itself did until its prefix existed.
  */
 export const TokenKind = {
   API_KEY: AuthMethod.API_KEY,
   DEPLOY_TOKEN: AuthMethod.TOKEN,
+  OAUTH: AuthMethod.OAUTH,
   OPAQUE: 'opaque',
 } as const;
 
@@ -1838,9 +1883,54 @@ export type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
 export function classifyToken(token: string): TokenKindType {
   if (token.startsWith(API_KEY.PREFIX)) return TokenKind.API_KEY;
   if (token.startsWith(DEPLOY_TOKEN.PREFIX)) return TokenKind.DEPLOY_TOKEN;
+  if (token.startsWith(OAUTH_TOKEN.PREFIX)) return TokenKind.OAUTH;
   return TokenKind.OPAQUE;
 }
 
+/** The auth-scheme, lowercased — the form the comparison is made in. */
+const BEARER_SCHEME = 'bearer ';
+
+/**
+ * Read the credential out of an `Authorization` header value — the step
+ * BEFORE `classifyToken`, and the other half of the one wire slot this
+ * section owns.
+ *
+ * Returns the credential's own bytes, or `null` when the header carries a
+ * foreign scheme or nothing after the scheme.
+ *
+ * **The scheme is folded; the credential is not.** RFC 7235 §2.1 makes the
+ * auth-scheme case-insensitive, so `bearer`, `Bearer` and `BEARER` are the
+ * same header. The value after it is opaque and is compared literally
+ * everywhere it is used — `ship-`/`deploy-`/`oauth-` are lowercase hex, and
+ * folding them would make a credential match values it is not.
+ *
+ * **This platform has paid for the rule twice, which is why it has an owner
+ * rather than a convention.** A spec-conformant `bearer ship-…` client was
+ * refused for as long as the API's scheme test was spelled case-sensitively;
+ * and `@better-auth/oauth-provider` carries the same defect in four places
+ * today (`startsWith("Bearer ")`), which is precisely why the platform folds
+ * the scheme itself and hands the provider a bare token.
+ *
+ * **ABSENCE is deliberately not this function's business.** A missing header
+ * and an unreadable one are different facts, and the callers that care split
+ * on them: the API worker's middleware distinguishes `absent` (the only
+ * anonymous path) from `unreadable` (a presented credential that is refused),
+ * and collapsing the two here would take that distinction away from the layer
+ * that needs it. Callers check for the header themselves and pass its value.
+ *
+ * **Why this lives in the constitution rather than in a worker's `shared/`.**
+ * It is the same wire boundary `classifyToken` already owns — one reads the
+ * slot, the other dispatches on what came out — and a rule with two holders
+ * whose drift is silent earns exactly one owner regardless of what the
+ * convoy costs. The estate's recorded refusal to own a `Bearer` CONSTANT
+ * stands and is a different thing: that is RFC vocabulary, the same reason
+ * this package owns no `"POST"`. A parser is not a spelling.
+ */
+export function readBearerValue(header: string): string | null {
+  if (header.slice(0, BEARER_SCHEME.length).toLowerCase() !== BEARER_SCHEME) return null;
+  return header.slice(BEARER_SCHEME.length) || null;
+}
+
 /**
  * OAuth scope vocabulary for delegated third-party access tokens.
  * Single source of truth used by the authorization server (advertised in
@@ -1988,11 +2078,25 @@ export function validateDeployToken(deployToken: string): void {
   validatePrefixedCredential(deployToken, DEPLOY_TOKEN, 'Deploy token');
 }
 
+/**
+ * Validate OAuth access token format
+ */
+export function validateOAuthToken(oauthToken: string): void {
+  validatePrefixedCredential(oauthToken, OAUTH_TOKEN, 'OAuth access token');
+}
+
 /**
  * Validate a client token of any population. Classifies by shape and applies
- * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
- * validated strictly; opaque tokens (OAuth access tokens, future populations)
- * only need to be non-empty — their validity is the server's to decide.
+ * the matching format rules: all three prefixed populations are validated
+ * strictly; an OPAQUE token only needs to be non-empty.
+ *
+ * **The OPAQUE arm stays permissive on purpose**, even though the platform no
+ * longer mints an unprefixed credential. It is the fallback for a population
+ * that does not exist yet, and a client refusing a shape the server would
+ * accept is the one failure mode this boundary must never have — the server
+ * decides, and it refuses an unrecognised bearer anyway. Unprefixed OAuth
+ * tokens from before 2026-08-14 land here and are refused server-side, which
+ * is correct: they were revoked by the change, not grandfathered.
  */
 export function validateToken(token: string): void {
   switch (classifyToken(token)) {
@@ -2002,6 +2106,9 @@ export function validateToken(token: string): void {
     case TokenKind.DEPLOY_TOKEN:
       validateDeployToken(token);
       return;
+    case TokenKind.OAUTH:
+      validateOAuthToken(token);
+      return;
     case TokenKind.OPAQUE:
       if (!token) throw ShipError.validation('Token must be a non-empty string');
   }