@company-semantics/contracts 39.7.0 → 39.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "39.7.0",
+  "version": "39.8.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -907,6 +907,17 @@ export type {
   DisableSecretRequest,
 } from "./security/index";
 
+// Auth token storage/entropy policy (PRD-00901)
+// @see src/security/token-policy.ts — single source for the runtime issuance
+// path and the secure-token-generation CI guard
+export { AUTH_TOKEN_POLICY_REQUIREMENTS } from "./security/index";
+export type {
+  TokenStorageFormat,
+  TokenPolicyConformance,
+  TokenPolicyRequirement,
+  AuthTokenPolicyClass,
+} from "./security/index";
+
 // Analytics response metadata (shared vocabulary for OLTP/OLAP separation)
 // @see ADR-CTRL-053 for design rationale
 export type {

package/src/security/index.ts

@@ -19,3 +19,11 @@ export type {
   RotateSecretRequest,
   DisableSecretRequest,
 } from "./org-secrets";
+
+export { AUTH_TOKEN_POLICY_REQUIREMENTS } from "./token-policy";
+export type {
+  TokenStorageFormat,
+  TokenPolicyConformance,
+  TokenPolicyRequirement,
+  AuthTokenPolicyClass,
+} from "./token-policy";

package/src/security/token-policy.ts

@@ -0,0 +1,113 @@
+/**
+ * Declared storage and entropy policy for auth-bearing tokens.
+ *
+ * This is the single source consumed by BOTH the runtime issuance path and the
+ * secure-token-generation CI guard. A declaration with no enforcing consumer is
+ * the defect class this module exists to close.
+ *
+ * Every field states what an implementation MUST satisfy. None of them describe
+ * what the code does today — that is `conformance`, and it is mandatory per
+ * class. Keeping the two apart is the point: a requirement record that reads as
+ * a description silently re-asserts the guarantee it was written to obtain, and
+ * is the same declaration-without-enforcement defect wearing a different hat.
+ */
+export type TokenStorageFormat = "hashed" | "hmac-signed" | "encrypted";
+
+/**
+ * Whether every known issuance site already satisfies the declared requirement.
+ *
+ * `enforced` — no known site violates it.
+ * `unmet` — at least one known site violates it; `gap` names what is wrong.
+ *
+ * This is NOT a suppression and confers no exemption. The requirement holds
+ * either way and the secure-token-generation guard reports the violating sites
+ * regardless — the field exists so the canonical record cannot be read as
+ * asserting a guarantee the implementation has not yet earned.
+ */
+export type TokenPolicyConformance =
+  | { readonly status: "enforced" }
+  | { readonly status: "unmet"; readonly gap: string };
+
+export interface TokenPolicyRequirement {
+  /** Minimum entropy the raw token must carry, in bits. */
+  readonly minEntropyBits: number;
+  /** Algorithm the stored representation must be derived with. */
+  readonly hashAlgorithm: string;
+  /**
+   * How the token must be persisted. Never 'plaintext' — that is not a member,
+   * because plaintext is never an acceptable requirement. A class that IS
+   * persisted in plaintext today says so through `conformance`, which is why
+   * the union does not need to express it.
+   */
+  readonly storageFormat: TokenStorageFormat;
+  /**
+   * Whether the implementation currently meets the requirement above. Required,
+   * not optional: an omitted status would default to an unearned claim, which
+   * is exactly the drift this record exists to surface.
+   */
+  readonly conformance: TokenPolicyConformance;
+  /**
+   * Identifier / function-name patterns that bind a call site to this policy
+   * class. Heuristic only: the AUTHORITATIVE binding is the explicit policy
+   * argument passed at the generation site. These patterns exist so the guard
+   * can flag an UNCLASSIFIED site, never to silently classify one.
+   */
+  readonly contextPatterns: readonly string[];
+}
+
+export const AUTH_TOKEN_POLICY_REQUIREMENTS = {
+  SessionToken: {
+    minEntropyBits: 256,
+    hashAlgorithm: "SHA-256",
+    storageFormat: "hashed",
+    contextPatterns: ["session"],
+    conformance: {
+      status: "unmet",
+      gap:
+        "Minted with randomUUID() (122 bits) and persisted verbatim: sessions.token " +
+        "holds the cookie value itself, and lookup is raw equality against it.",
+    },
+  },
+  ChatShareToken: {
+    minEntropyBits: 256,
+    hashAlgorithm: "SHA-256",
+    storageFormat: "hashed",
+    contextPatterns: ["share"],
+    conformance: {
+      status: "unmet",
+      gap:
+        "Minted with randomBytes(32) and persisted verbatim: chat_shares.token holds " +
+        "the share-URL value itself, and lookup is raw equality against it.",
+    },
+  },
+  InviteToken: {
+    minEntropyBits: 256,
+    hashAlgorithm: "SHA-256",
+    storageFormat: "hashed",
+    contextPatterns: ["invite"],
+    conformance: { status: "enforced" },
+  },
+  OAuthStateToken: {
+    minEntropyBits: 128,
+    hashAlgorithm: "HMAC-SHA256",
+    storageFormat: "hmac-signed",
+    contextPatterns: ["state", "nonce"],
+    conformance: { status: "enforced" },
+  },
+  OTPCode: {
+    minEntropyBits: 20,
+    hashAlgorithm: "bcrypt",
+    storageFormat: "hashed",
+    contextPatterns: ["otp", "loginCode"],
+    conformance: { status: "enforced" },
+  },
+  OAuthTokenEncryption: {
+    minEntropyBits: 256,
+    hashAlgorithm: "AES-256-GCM",
+    storageFormat: "encrypted",
+    contextPatterns: ["tokenEncryption"],
+    conformance: { status: "enforced" },
+  },
+} as const satisfies Record<string, TokenPolicyRequirement>;
+
+export type AuthTokenPolicyClass = keyof typeof AUTH_TOKEN_POLICY_REQUIREMENTS;