@company-semantics/contracts 39.6.1 → 39.8.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'b02ad24e598a' as const;
-export const SPEC_HASH_FULL = 'b02ad24e598abefeaaa58e146e9784fea88bc3abbd1af8b24a7d9c5d947db757' as const;
+export const SPEC_HASH = 'e8cf36a33d43' as const;
+export const SPEC_HASH_FULL = 'e8cf36a33d43bec5e4383c8edbfbdccd37fe8d081a5ddd02e96c83cb5e7bd21a' as const;

package/src/api/generated.ts

@@ -4740,6 +4740,8 @@ export interface components {
         };
         AccessRequestCreate: {
             message?: string;
+            /** @enum {string} */
+            requestedAccessLevel?: "editor" | "commenter" | "viewer";
         };
         ApproveAccessRequest: {
             /** @enum {string} */

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/notifications/__tests__/__snapshots__/registry.test.ts.snap

@@ -15,6 +15,7 @@ exports[`NOTIFICATION_DEFINITIONS > titles every kind 1`] = `
   "companyMd.access_request_denied · No reason": "Your access request was reviewed",
   "companyMd.access_request_denied · With reason": "Your access request was reviewed",
   "companyMd.access_requested · No message": "Someone requested access to a document",
+  "companyMd.access_requested · Requested editor": "Someone requested access to a document",
   "companyMd.access_requested · With message": "Someone requested access to a document",
   "org.invite · Admin": "You've been invited to join Acme Corp on Company Semantics",
   "org.invite · Member": "You've been invited to join Acme Corp on Company Semantics",

package/src/notifications/__tests__/fixtures.ts

@@ -198,6 +198,13 @@ add("companyMd.access_requested", "No message", {
   docTitle: "Engineering Handbook",
   reviewUrl: `${APP}/doc/handbook?request=req_456`,
 });
+add("companyMd.access_requested", "Requested editor", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  message: "I maintain this section day to day — may I edit it directly?",
+  requestedAccessLevel: "editor",
+  reviewUrl: `${APP}/doc/handbook?request=req_789`,
+});
 
 add("companyMd.access_request_approved", "Editor", {
   approverName: "Jordan Lee",

package/src/notifications/kinds/company-md-access-requested.ts

@@ -8,11 +8,28 @@
 
 import type { NotificationDefinition } from "../definition";
 
+/**
+ * How each requestable band reads in prose ("requested edit access") and in the
+ * key-value table ("Editor"). Absent band ⇒ band-neutral copy, so senders that
+ * predate `requestedAccessLevel` (ADR-CONTRACTS-098) render exactly as before.
+ */
+const LEVEL_PHRASE = {
+  viewer: "view",
+  commenter: "comment",
+  editor: "edit",
+} as const;
+const LEVEL_LABEL = {
+  viewer: "Viewer",
+  commenter: "Commenter",
+  editor: "Editor",
+} as const;
+
 export const accessRequestedDefinition: NotificationDefinition<"companyMd.access_requested"> =
   {
     kind: "companyMd.access_requested",
     compose: (payload, context) => {
-      const { requesterName, docTitle, message, reviewUrl } = payload;
+      const { requesterName, docTitle, message, requestedAccessLevel, reviewUrl } =
+        payload;
 
       return {
         metadata: {
@@ -23,7 +40,12 @@ export const accessRequestedDefinition: NotificationDefinition<"companyMd.access
           {
             elements: [
               { type: "greeting" },
-              { type: "body", text: "Someone requested document access." },
+              {
+                type: "body",
+                text: requestedAccessLevel
+                  ? `Someone requested ${LEVEL_PHRASE[requestedAccessLevel]} access to a document.`
+                  : "Someone requested document access.",
+              },
               {
                 type: "chatUnit",
                 items: [
@@ -47,6 +69,14 @@ export const accessRequestedDefinition: NotificationDefinition<"companyMd.access
                 rows: [
                   { label: "From", value: requesterName },
                   { label: "Document", value: `"${docTitle}"` },
+                  ...(requestedAccessLevel
+                    ? [
+                        {
+                          label: "Requested",
+                          value: LEVEL_LABEL[requestedAccessLevel],
+                        },
+                      ]
+                    : []),
                 ],
               },
               {

package/src/notifications/payloads.ts

@@ -132,6 +132,12 @@ export interface NotificationPayloads {
     docTitle: string;
     /** Optional message from the requester (notification only) */
     message?: string;
+    /**
+     * The band the requester asked for (ADR-CONTRACTS-098): names the intent
+     * in the owner's email ("requested edit access"). Absent = unspecified
+     * (older senders / clients) — the copy stays band-neutral.
+     */
+    requestedAccessLevel?: "viewer" | "commenter" | "editor";
     /** Deep-link that opens the doc's ShareDialog scrolled to the pending request */
     reviewUrl: string;
   };

package/src/permissions/access-request.ts

@@ -28,6 +28,15 @@ export type AccessRequestStatus = z.infer<typeof AccessRequestStatusSchema>;
 export const AccessRequestCreateSchema = z.object({
   /** Optional context the requester sends to the owner(s). */
   message: z.string().max(2000).optional(),
+  /**
+   * The band the requester is asking for (ADR-CONTRACTS-098 / ADR-BE-454):
+   * `viewer` from the locked preview, `editor` from the view-only Editor tab
+   * (elevation, ADR-BE-453). A REQUEST, not a claim — the owner still chooses
+   * the granted band on approval; this only seeds their picker. Optional so
+   * older clients keep working (absent ⇒ unspecified, owners default to
+   * viewer).
+   */
+  requestedAccessLevel: GrantableAccessLevelSchema.optional(),
 });
 export type AccessRequestCreate = z.infer<typeof AccessRequestCreateSchema>;
 
@@ -45,6 +54,12 @@ export const AccessRequestSchema = z.object({
   docId: z.string(),
   status: AccessRequestStatusSchema,
   message: z.string().nullable(),
+  /**
+   * The band the requester asked for (ADR-CONTRACTS-098) — seeds the owner
+   * inbox's approval picker. Null for requests filed before the field existed
+   * or by clients that did not specify one.
+   */
+  requestedAccessLevel: GrantableAccessLevelSchema.nullable(),
   createdAt: z.string(),
   resolvedAt: z.string().nullable(),
 });

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;