@serve.zone/interfaces 19.8.0 → 20.1.0

package/ts/private/canonicaljson.ts

@@ -0,0 +1,221 @@
+export const strictCanonicalJsonRules = Object.freeze({
+  version: 1 as const,
+  encoding: 'utf-8' as const,
+  objectKeyOrdering: 'utf-16-code-unit-ascending' as const,
+  arrayOrdering: 'preserved-dense' as const,
+  unicodeNormalization: 'preserved' as const,
+  numberEncoding: 'safe-integer-json-no-negative-zero' as const,
+  digest: 'sha256-lowercase-hex' as const,
+});
+
+export type TCanonicalJsonFailure = (reasonArg: string) => never;
+
+const assertUnicodeScalarString = (
+  valueArg: string,
+  fieldNameArg: string,
+  failArg: TCanonicalJsonFailure,
+): void => {
+  for (let index = 0; index < valueArg.length; index++) {
+    const codeUnit = valueArg.charCodeAt(index);
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const followingCodeUnit = valueArg.charCodeAt(index + 1);
+      if (
+        !Number.isInteger(followingCodeUnit) ||
+        followingCodeUnit < 0xdc00 ||
+        followingCodeUnit > 0xdfff
+      ) {
+        failArg(`${fieldNameArg} must not contain an unpaired UTF-16 surrogate`);
+      }
+      index++;
+      continue;
+    }
+    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      failArg(`${fieldNameArg} must not contain an unpaired UTF-16 surrogate`);
+    }
+  }
+};
+
+const readStrictRecord = (
+  valueArg: object,
+  fieldNameArg: string,
+  failArg: TCanonicalJsonFailure,
+): Record<string, unknown> => {
+  const prototype = Object.getPrototypeOf(valueArg);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return failArg(`${fieldNameArg} must be a plain object`);
+  }
+  const record = valueArg as Record<string, unknown>;
+  const ownKeys = Reflect.ownKeys(record);
+  if (ownKeys.some((keyArg) => typeof keyArg !== 'string')) {
+    return failArg(`${fieldNameArg} must not contain symbol keys`);
+  }
+  for (const key of ownKeys as string[]) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (
+      !descriptor ||
+      !descriptor.enumerable ||
+      !Object.hasOwn(descriptor, 'value')
+    ) {
+      return failArg(
+        `${fieldNameArg} must contain enumerable data properties only`,
+      );
+    }
+  }
+  return record;
+};
+
+const readStrictArray = (
+  valueArg: unknown[],
+  fieldNameArg: string,
+  failArg: TCanonicalJsonFailure,
+): unknown[] => {
+  if (Object.getPrototypeOf(valueArg) !== Array.prototype) {
+    return failArg(`${fieldNameArg} must be a dense plain array`);
+  }
+  for (let index = 0; index < valueArg.length; index++) {
+    if (!Object.hasOwn(valueArg, index)) {
+      return failArg(`${fieldNameArg} must not contain sparse entries`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+    if (
+      !descriptor ||
+      !descriptor.enumerable ||
+      !Object.hasOwn(descriptor, 'value')
+    ) {
+      return failArg(`${fieldNameArg} must contain enumerable data entries only`);
+    }
+  }
+  for (const key of Reflect.ownKeys(valueArg)) {
+    if (key === 'length') {
+      continue;
+    }
+    if (
+      typeof key !== 'string' ||
+      !/^(?:0|[1-9][0-9]*)$/.test(key) ||
+      Number(key) >= valueArg.length
+    ) {
+      return failArg(`${fieldNameArg} must not contain extra properties`);
+    }
+  }
+  return valueArg;
+};
+
+export const canonicalizeStrictJson = (
+  valueArg: unknown,
+  failArg: TCanonicalJsonFailure,
+  fieldNameArg = 'canonical JSON input',
+): string => {
+  const ancestors = new Set<object>();
+
+  const visit = (currentValueArg: unknown, currentFieldNameArg: string): string => {
+    if (currentValueArg === null) {
+      return 'null';
+    }
+    if (typeof currentValueArg === 'boolean') {
+      return currentValueArg ? 'true' : 'false';
+    }
+    if (typeof currentValueArg === 'string') {
+      assertUnicodeScalarString(currentValueArg, currentFieldNameArg, failArg);
+      return JSON.stringify(currentValueArg);
+    }
+    if (typeof currentValueArg === 'number') {
+      if (
+        !Number.isSafeInteger(currentValueArg) ||
+        Object.is(currentValueArg, -0)
+      ) {
+        return failArg(`${currentFieldNameArg} must contain safe integers only`);
+      }
+      return String(currentValueArg);
+    }
+    if (!currentValueArg || typeof currentValueArg !== 'object') {
+      return failArg(`${currentFieldNameArg} contains a non-JSON value`);
+    }
+    if (ancestors.has(currentValueArg)) {
+      return failArg(`${currentFieldNameArg} contains a cycle`);
+    }
+
+    ancestors.add(currentValueArg);
+    try {
+      if (Array.isArray(currentValueArg)) {
+        const array = readStrictArray(
+          currentValueArg,
+          currentFieldNameArg,
+          failArg,
+        );
+        return `[${array
+          .map((entryArg, indexArg) =>
+            visit(entryArg, `${currentFieldNameArg}[${indexArg}]`),
+          )
+          .join(',')}]`;
+      }
+
+      const record = readStrictRecord(
+        currentValueArg,
+        currentFieldNameArg,
+        failArg,
+      );
+      const keys = Object.keys(record).sort((leftArg, rightArg) => {
+        return leftArg < rightArg ? -1 : leftArg > rightArg ? 1 : 0;
+      });
+      return `{${keys
+        .map((keyArg) => {
+          assertUnicodeScalarString(
+            keyArg,
+            `${currentFieldNameArg} key`,
+            failArg,
+          );
+          return `${JSON.stringify(keyArg)}:${visit(
+            record[keyArg],
+            `${currentFieldNameArg}.${keyArg}`,
+          )}`;
+        })
+        .join(',')}}`;
+    } finally {
+      ancestors.delete(currentValueArg);
+    }
+  };
+
+  return visit(valueArg, fieldNameArg);
+};
+
+export const createSha256Hex = async (
+  contentsArg: Uint8Array,
+  failArg: TCanonicalJsonFailure,
+): Promise<string> => {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    return failArg('Web Crypto SHA-256 is unavailable in this runtime');
+  }
+  const digest = await subtle.digest('SHA-256', new Uint8Array(contentsArg));
+  return Array.from(new Uint8Array(digest), (byteArg) =>
+    byteArg.toString(16).padStart(2, '0'),
+  ).join('');
+};
+
+export const createCanonicalJsonSha256Hex = async (
+  canonicalJsonArg: string,
+  failArg: TCanonicalJsonFailure,
+): Promise<string> => {
+  return createSha256Hex(new TextEncoder().encode(canonicalJsonArg), failArg);
+};
+
+export const deepFreezeValue = <T>(
+  valueArg: T,
+  seenArg = new WeakSet<object>(),
+): T => {
+  if (!valueArg || typeof valueArg !== 'object') {
+    return valueArg;
+  }
+  const object = valueArg as object;
+  if (ArrayBuffer.isView(object) || seenArg.has(object)) {
+    return valueArg;
+  }
+  seenArg.add(object);
+  for (const key of Reflect.ownKeys(object)) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor && Object.hasOwn(descriptor, 'value')) {
+      deepFreezeValue(descriptor.value, seenArg);
+    }
+  }
+  return Object.freeze(valueArg);
+};

package/ts/requests/index.ts

@@ -25,6 +25,7 @@ import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
 import * as routingRequests from './routing.js';
+import * as secretRequests from './secret.js';
 import * as secretBundleRequests from './secretbundle.js';
 import * as secretGroupRequests from './secretgroup.js'; 
 import * as serverRequests from './server.js';
@@ -61,6 +62,7 @@ export {
   nodeRequests as node,
   platformRequests as platform,
   routingRequests as routing,
+  secretRequests as secret,
   secretBundleRequests as secretbundle,
   secretGroupRequests as secretgroup,
   serverRequests as server,

package/ts/requests/secret.ts

@@ -0,0 +1,256 @@
+import type * as plugins from '../plugins.js';
+import type {
+  IResolvedSecretManifestEntry,
+  ISecretMetadata,
+  ISecretSetAttachment,
+  ISecretSetConsumerRolloutStatus,
+  ISecretSetMetadata,
+  ISecretVersionMetadata,
+  ISecretVersionRetentionReference,
+  TSecretDelivery,
+  TSecretEnvironment,
+} from '../data/secret.js';
+import type { IIdentityCredential } from '../data/user.js';
+
+export type TSecretMutationTarget =
+  | { kind: 'service'; serviceId: string }
+  | { kind: 'secret-set'; secretSetId: string };
+
+export type TSecretValueInput =
+  | { mode: 'provided'; value: string }
+  /** Server-generated runtime-only value; plaintext is never returned. */
+  | { mode: 'generated'; bytes: 32 | 48 | 64 };
+
+export interface IReq_ListSecrets extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListSecrets
+> {
+  method: 'listSecrets';
+  request: {
+    identity: IIdentityCredential;
+    target: TSecretMutationTarget;
+    environment?: TSecretEnvironment;
+  };
+  response: {
+    secrets: ISecretMetadata[];
+    /** Observable CAS fence for the selected service or SecretSet. */
+    targetSecretsRevision: number;
+  };
+}
+
+export interface IReq_GetSecretMetadata extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretMetadata
+> {
+  method: 'getSecretMetadata';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+  };
+  response: {
+    secret: ISecretMetadata;
+    versions: ISecretVersionMetadata[];
+  };
+}
+
+export interface IReq_CreateSecret extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateSecret
+> {
+  method: 'createSecret';
+  request: {
+    identity: IIdentityCredential;
+    target: TSecretMutationTarget;
+    key: string;
+    environment: TSecretEnvironment;
+    name: string;
+    description?: string;
+    tags?: Array<{ key: string; value: string }>;
+    delivery: TSecretDelivery;
+    valueInput: TSecretValueInput;
+    expectedTargetSecretsRevision: number;
+  };
+  response: {
+    secret: ISecretMetadata;
+    version: ISecretVersionMetadata;
+    /** Post-create CAS revision for the selected target. */
+    targetSecretsRevision: number;
+  };
+}
+
+export interface IReq_RotateSecret extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RotateSecret
+> {
+  method: 'rotateSecret';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+    valueInput: TSecretValueInput;
+    expectedSecretRevision: number;
+    expectedActiveVersionId?: string;
+  };
+  response: {
+    secret: ISecretMetadata;
+    version: ISecretVersionMetadata;
+  };
+}
+
+export interface IReq_ChangeSecretLifecycle extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ChangeSecretLifecycle
+> {
+  method: 'changeSecretLifecycle';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+    action: 'retire' | 'revoke' | 'delete' | 'request-purge';
+    expectedSecretRevision: number;
+  };
+  response: {
+    secret: ISecretMetadata;
+  };
+}
+
+export interface IReq_GetSecretVersionPurgePreflight
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretVersionPurgePreflight
+> {
+  method: 'getSecretVersionPurgePreflight';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+    secretVersionId: string;
+  };
+  response: {
+    purgeAllowed: boolean;
+    references: ISecretVersionRetentionReference[];
+  };
+}
+
+export interface IReq_ListSecretSets extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListSecretSets
+> {
+  method: 'listSecretSets';
+  request: {
+    identity: IIdentityCredential;
+    organizationId: string;
+  };
+  response: {
+    secretSets: ISecretSetMetadata[];
+  };
+}
+
+export interface IReq_CreateSecretSet extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateSecretSet
+> {
+  method: 'createSecretSet';
+  request: {
+    identity: IIdentityCredential;
+    organizationId: string;
+    name: string;
+    description?: string;
+  };
+  response: {
+    secretSet: ISecretSetMetadata;
+  };
+}
+
+export interface IReq_UpdateSecretSet extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_UpdateSecretSet
+> {
+  method: 'updateSecretSet';
+  request: {
+    identity: IIdentityCredential;
+    secretSetId: string;
+    name: string;
+    description?: string;
+    expectedRevision: number;
+  };
+  response: {
+    secretSet: ISecretSetMetadata;
+  };
+}
+
+export interface IReq_ChangeSecretSetLifecycle
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ChangeSecretSetLifecycle
+> {
+  method: 'changeSecretSetLifecycle';
+  request: {
+    identity: IIdentityCredential;
+    secretSetId: string;
+    action: 'retire' | 'delete';
+    expectedRevision: number;
+  };
+  response: {
+    secretSet: ISecretSetMetadata;
+  };
+}
+
+export interface IReq_GetSecretSetConsumerRollout
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretSetConsumerRollout
+> {
+  method: 'getSecretSetConsumerRollout';
+  request: {
+    identity: IIdentityCredential;
+    secretSetId: string;
+    rolloutId: string;
+    cursor?: string;
+    limit?: number;
+  };
+  response: {
+    consumers: ISecretSetConsumerRolloutStatus[];
+    nextCursor?: string;
+  };
+}
+
+export interface IReq_SetServiceSecretSetAttachments
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SetServiceSecretSetAttachments
+> {
+  method: 'setServiceSecretSetAttachments';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    attachments: ISecretSetAttachment[];
+    expectedSecretConfigurationRevision: number;
+  };
+  response: {
+    attachments: ISecretSetAttachment[];
+    /** Post-update attachment CAS revision. */
+    secretConfigurationRevision: number;
+  };
+}
+
+export interface ISecretResolutionPreviewCollision {
+  environment: TSecretEnvironment;
+  key: string;
+  sourceSecretIds: string[];
+  reason: 'duplicate-secret-set-key' | 'duplicate-service-key' | 'invalid-alias';
+}
+
+export interface IReq_PreviewServiceSecretResolution
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PreviewServiceSecretResolution
+> {
+  method: 'previewServiceSecretResolution';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    attachments?: ISecretSetAttachment[];
+  };
+  response: {
+    entries: IResolvedSecretManifestEntry[];
+    collisions: ISecretResolutionPreviewCollision[];
+  };
+}

package/ts/runtime.ts

@@ -0,0 +1,80 @@
+import type * as plugins from './plugins.js';
+import type {
+  IIdentityCredential,
+  IResolvedSecretManifest,
+  TSha256Digest,
+} from './data/index.js';
+import {
+  validateResolvedSecretManifest,
+  verifyResolvedSecretManifestDigest,
+} from './data/secret.js';
+
+/**
+ * Runtime-only material. This module is exported only under the Node condition
+ * and is intentionally unreachable from the universal/browser-facing barrel.
+ */
+export interface IResolvedSecretMaterialValue {
+  secretVersionId: string;
+  value: string;
+}
+
+export interface IResolvedSecretMaterial {
+  schemaVersion: 1;
+  /** Full value-free manifest so the runtime can verify its canonical digest. */
+  manifest: IResolvedSecretManifest;
+  /** Plaintext values keyed only by the exact version IDs pinned by the manifest. */
+  values: IResolvedSecretMaterialValue[];
+}
+
+/**
+ * Verifies the immutable manifest and requires exactly one material value for
+ * every pinned version. Callers separately compare the verified manifest
+ * reference to the request and their authenticated cluster scope.
+ */
+export const verifyResolvedSecretMaterial = async (
+  materialArg: unknown,
+): Promise<boolean> => {
+  if (!materialArg || typeof materialArg !== 'object' || Array.isArray(materialArg)) return false;
+  const material = materialArg as Partial<IResolvedSecretMaterial>;
+  if (!material.manifest || !Array.isArray(material.values)) return false;
+  if (material.schemaVersion !== 1) return false;
+  if (validateResolvedSecretManifest(material.manifest).length > 0) return false;
+  if (!await verifyResolvedSecretManifestDigest(material.manifest)) return false;
+  if (!material.values.every((valueArg) => (
+    Boolean(valueArg)
+    && typeof valueArg === 'object'
+    && typeof valueArg.secretVersionId === 'string'
+    && typeof valueArg.value === 'string'
+  ))) return false;
+  const expectedVersionIds = material.manifest.entries
+    .map((entryArg) => entryArg.secretVersionId)
+    .sort();
+  const actualVersionIds = material.values
+    .map((valueArg) => valueArg.secretVersionId)
+    .sort();
+  return new Set(actualVersionIds).size === actualVersionIds.length
+    && JSON.stringify(actualVersionIds) === JSON.stringify(expectedVersionIds);
+};
+
+/**
+ * Cluster and organization are derived from the verified JWT. A caller cannot
+ * select either scope through request fields.
+ */
+export interface IReq_GetResolvedSecretMaterial
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetResolvedSecretMaterial
+> {
+  method: 'getResolvedSecretMaterial';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    secretRolloutId: string;
+    secretRolloutGeneration: number;
+    manifestId: string;
+    manifestDigest: TSha256Digest;
+  };
+  response: {
+    material: IResolvedSecretMaterial;
+  };
+}