@company-semantics/contracts 2.4.0 → 2.5.0

package/package.json

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

package/src/content/schemas.ts

@@ -99,7 +99,14 @@ const AclEntrySchema = z.object({
 });
 
 const AccessReasonSchema = z.object({
-  source: z.enum(['org_rbac', 'sharing_policy', 'unit_baseline', 'acl_grant', 'doc_ownership']),
+  source: z.enum([
+    'org_rbac',
+    'sharing_policy',
+    'unit_baseline',
+    'unit_delegation',
+    'acl_grant',
+    'doc_ownership',
+  ]),
   detail: z.string(),
 });
 

package/src/index.ts

@@ -663,6 +663,26 @@ export { openApiRoutes, type OpenApiRoute, type OpenApiMethod } from './generate
 export type { Secret } from './security/index'
 export { wrapSecret, unwrapSecret } from './security/index'
 
+// Org Secrets DTO schemas (PRD-00629) — masked-prefix-only, no value field
+export {
+  UsageClassSchema,
+  OrgSecretsActionSchema,
+  SecretValueStringSchema,
+  OrgSecretSummarySchema,
+  CreateSecretRequestSchema,
+  RotateSecretRequestSchema,
+  DisableSecretRequestSchema,
+} from './security/org-secrets'
+export type {
+  UsageClass,
+  OrgSecretsAction,
+  SecretValueString,
+  OrgSecretSummary,
+  CreateSecretRequest,
+  RotateSecretRequest,
+  DisableSecretRequest,
+} from './security/org-secrets'
+
 // Analytics response metadata (shared vocabulary for OLTP/OLAP separation)
 // @see ADR-CTRL-053 for design rationale
 export type { AnalyticsBackend, AnalyticsResponseMeta } from './types/analytics'

package/src/security/index.ts

@@ -1,2 +1,21 @@
 export type { Secret } from './secret';
 export { wrapSecret, unwrapSecret } from './secret';
+
+export {
+  UsageClassSchema,
+  OrgSecretsActionSchema,
+  SecretValueStringSchema,
+  OrgSecretSummarySchema,
+  CreateSecretRequestSchema,
+  RotateSecretRequestSchema,
+  DisableSecretRequestSchema,
+} from './org-secrets';
+export type {
+  UsageClass,
+  OrgSecretsAction,
+  SecretValueString,
+  OrgSecretSummary,
+  CreateSecretRequest,
+  RotateSecretRequest,
+  DisableSecretRequest,
+} from './org-secrets';

package/src/security/org-secrets.ts

@@ -0,0 +1,100 @@
+/**
+ * Org Secrets — DTO schemas
+ *
+ * Zod schemas for the org_secrets surface (PRD-00629). The contracts package
+ * defines what admin clients may observe and submit. The decrypted credential
+ * value is intentionally absent from every surface here — the only
+ * credential-derived field exposed is `maskedPrefix`.
+ *
+ * Servers receiving plaintext (CreateSecretRequest / RotateSecretRequest)
+ * are expected to wrap it with {@link Secret} from `./secret` before storage,
+ * and never re-emit it to clients.
+ */
+import { z } from 'zod';
+
+/**
+ * Classification of how a credential is consumed at runtime. Drives downstream
+ * authorization and audit categorization.
+ */
+export const UsageClassSchema = z.enum(['AI_PROVIDER', 'WEBHOOK_SIGNING', 'GENERIC']);
+export type UsageClass = z.infer<typeof UsageClassSchema>;
+
+/**
+ * Auditable lifecycle and access events for an org secret. Used by the audit
+ * trail and observability surfaces; the schema is the closed enumeration.
+ */
+export const OrgSecretsActionSchema = z.enum([
+  'created',
+  'rotated',
+  'disabled',
+  'enabled',
+  'access_denied',
+  'explicit_export',
+  'unusual_access',
+]);
+export type OrgSecretsAction = z.infer<typeof OrgSecretsActionSchema>;
+
+/**
+ * Branded plaintext credential string. Bounded so accidental logs do not leak
+ * megabytes; branded to discourage propagation through generic string flows.
+ * Servers must wrap with Secret<T> before storage and never echo it back.
+ */
+export const SecretValueStringSchema = z
+  .string()
+  .min(1)
+  .max(8192)
+  .brand<'SecretValueString'>();
+export type SecretValueString = z.infer<typeof SecretValueStringSchema>;
+
+/**
+ * Admin-visible summary of an `org_secrets` row. The decrypted value is
+ * intentionally absent — `maskedPrefix` is the only credential-derived field
+ * exposed by this surface (INV-PRD-00629: no value in summary).
+ *
+ * `usageCount` is serialized as a string for cross-driver bigint safety.
+ */
+export const OrgSecretSummarySchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid().nullable(),
+  usageClass: UsageClassSchema,
+  secretName: z.string().min(1).max(128),
+  maskedPrefix: z.string().min(1).max(64),
+  version: z.number().int().positive(),
+  enabled: z.boolean(),
+  lastUsedAt: z.string().datetime().nullable(),
+  usageCount: z.string(),
+  rotatedAt: z.string().datetime().nullable(),
+  createdAt: z.string().datetime(),
+});
+export type OrgSecretSummary = z.infer<typeof OrgSecretSummarySchema>;
+
+/**
+ * Request to create a new org secret. Server-side handlers must wrap
+ * `plaintext` in Secret<T> immediately on receipt.
+ */
+export const CreateSecretRequestSchema = z.object({
+  orgId: z.string().uuid().nullable(),
+  usageClass: UsageClassSchema,
+  secretName: z.string().min(1).max(128),
+  plaintext: SecretValueStringSchema,
+  reason: z.string().max(512).optional(),
+});
+export type CreateSecretRequest = z.infer<typeof CreateSecretRequestSchema>;
+
+/**
+ * Request to rotate an existing secret to a new plaintext value.
+ */
+export const RotateSecretRequestSchema = z.object({
+  newPlaintext: SecretValueStringSchema,
+  reason: z.string().max(512).optional(),
+});
+export type RotateSecretRequest = z.infer<typeof RotateSecretRequestSchema>;
+
+/**
+ * Request to disable an existing secret. A non-empty `reason` is required so
+ * the audit trail always captures why a credential was taken out of service.
+ */
+export const DisableSecretRequestSchema = z.object({
+  reason: z.string().min(1).max(512),
+});
+export type DisableSecretRequest = z.infer<typeof DisableSecretRequestSchema>;