@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/api/openapi/tooling/delegated_contract.mjs

@@ -0,0 +1,302 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { applyOverlay } from './overlay.mjs';
+import { apiRoot, canonicalJSON, httpMethods, operationEntries, readStructured, sha256 } from './project.mjs';
+import { reserveStaticRouteSegments } from './route_contract.mjs';
+
+const componentKinds = Object.freeze([
+  'callbacks',
+  'examples',
+  'headers',
+  'links',
+  'parameters',
+  'pathItems',
+  'requestBodies',
+  'responses',
+  'schemas',
+]);
+
+export async function composeDelegatedContracts(service, source) {
+  let document = structuredClone(source);
+  const evidence = [];
+  for (const delegated of service.delegated_contracts ?? []) {
+    const artifactPath = resolve(apiRoot, delegated.artifact);
+    const artifactBytes = await readFile(artifactPath);
+    const artifact = JSON.parse(artifactBytes.toString('utf8'));
+    const provenance = await readStructured(resolve(apiRoot, delegated.provenance));
+    const overlayPath = resolve(apiRoot, delegated.overlay);
+    const overlayBytes = await readFile(overlayPath);
+    const overlay = await readStructured(overlayPath);
+    verifyProvenance(artifactBytes, artifact, provenance, {
+      expectedOperationCount: delegated.expected_operation_count,
+      overlayBytes,
+    });
+    const result = composeDelegatedDocument(document, artifact, overlay, delegated);
+    document = result.document;
+    evidence.push({
+      artifact_sha256: provenance.artifact_sha256,
+      id: delegated.id,
+      operation_count: result.operationCount,
+      overlay_sha256: provenance.overlay_sha256,
+      revision: provenance.revision,
+      selection_sha256: provenance.selection_sha256,
+      source_sha256: provenance.source_sha256,
+    });
+  }
+  return { document, evidence };
+}
+
+export function verifyProvenance(artifactBytes, artifact, provenance, { expectedOperationCount, overlayBytes } = {}) {
+  if (provenance?.schema_version !== 1 || !/^[0-9a-f]{40}$/.test(provenance.revision ?? '')) {
+    throw new Error('delegated provenance must declare schema_version 1 and a full Git revision');
+  }
+  for (const field of ['artifact_sha256', 'full_contract_sha256', 'overlay_sha256', 'selection_sha256', 'source_sha256']) {
+    if (!/^[0-9a-f]{64}$/.test(provenance[field] ?? '')) throw new Error(`delegated provenance has invalid ${field}`);
+  }
+  if (!Number.isInteger(provenance.operation_count) || provenance.operation_count < 1) {
+    throw new Error('delegated provenance has invalid operation_count');
+  }
+  if (expectedOperationCount !== undefined && provenance.operation_count !== expectedOperationCount) {
+    throw new Error('delegated provenance operation count does not match the registry');
+  }
+  if (sha256(artifactBytes) !== provenance.artifact_sha256) throw new Error('delegated artifact SHA-256 does not match provenance');
+  if (overlayBytes !== undefined && sha256(overlayBytes) !== provenance.overlay_sha256) {
+    throw new Error('delegated overlay SHA-256 does not match provenance');
+  }
+  if (!artifactBytes.equals(Buffer.from(canonicalJSON(artifact)))) throw new Error('delegated artifact must use canonical JSON serialization');
+}
+
+export function composeDelegatedDocument(source, artifact, overlay, delegated) {
+  if (artifact?.openapi !== '3.1.1' || artifact?.jsonSchemaDialect !== 'https://json-schema.org/draft/2020-12/schema') {
+    throw new Error(`delegated contract ${delegated.id} must use OpenAPI 3.1.1 and JSON Schema 2020-12`);
+  }
+  if ((artifact.servers ?? []).length > 0) throw new Error(`delegated contract ${delegated.id} must not retain upstream servers`);
+  const transformed = applyOverlay(artifact, overlay);
+  const sourceOperations = operationEntries(artifact);
+  const transformedOperations = operationEntries(transformed);
+  if (sourceOperations.length !== transformedOperations.length) throw new Error(`delegated overlay ${delegated.id} changed the operation count`);
+  if (transformedOperations.length !== delegated.expected_operation_count) {
+    throw new Error(`delegated contract ${delegated.id} operation count does not match the registry`);
+  }
+
+  const namespaced = namespaceComponents(transformed, delegated.id);
+  reserveStaticRouteSegments(namespaced.paths);
+  const document = structuredClone(source);
+  document.paths ??= {};
+  document.components ??= {};
+  for (const kind of componentKinds) document.components[kind] ??= {};
+  mergeSecurityScheme(document, namespaced, delegated);
+
+  const allowedMethods = new Set(delegated.methods.map((method) => method.toLowerCase()));
+  for (const [path, pathItem] of Object.entries(namespaced.paths ?? {})) {
+    if (!path.startsWith('/')) throw new Error(`delegated path must be absolute: ${path}`);
+    const mountedPath = mountDelegatedPath(path, delegated);
+    if (document.paths[mountedPath]) throw new Error(`delegated path collides with native contract: ${mountedPath}`);
+    for (const method of httpMethods) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      if (!allowedMethods.has(method)) throw new Error(`delegated method is not allowed: ${method.toUpperCase()} ${path}`);
+      applyCSRFProtection(operation, delegated, method, mountedPath);
+      validateOperation(operation, delegated, method, path, mountedPath);
+    }
+    document.paths[mountedPath] = pathItem;
+  }
+
+  for (const kind of componentKinds) {
+    for (const [name, component] of Object.entries(namespaced.components?.[kind] ?? {})) {
+      if (Object.hasOwn(document.components[kind], name)) throw new Error(`delegated component collision: ${kind}/${name}`);
+      component['x-onex-audience'] = 'public';
+      component['x-onex-stability'] = 'stable';
+      document.components[kind][name] = component;
+    }
+    if (Object.keys(document.components[kind]).length === 0) delete document.components[kind];
+  }
+
+  const tags = new Map((document.tags ?? []).map((tag) => [tag.name, tag]));
+  for (const tag of namespaced.tags ?? []) {
+    if (!tags.has(tag.name)) tags.set(tag.name, { ...tag, description: tag.description?.trim() || `${tag.name} API 操作。` });
+  }
+	document.tags = [...tags.values()];
+	appendNavigationGroup(document, (namespaced.tags ?? []).map((tag) => tag.name), delegated.navigation_group);
+	reserveStaticRouteSegments(document.paths);
+	return { document, operationCount: transformedOperations.length };
+}
+
+function appendNavigationGroup(document, tagNames, groupName) {
+  if (!Array.isArray(document['x-tagGroups']) || document['x-tagGroups'].length === 0) {
+    throw new Error('delegated contract source must declare x-tagGroups');
+  }
+  const groups = document['x-tagGroups'];
+  let group = groups.find((candidate) => candidate.name === groupName);
+  if (group === undefined) {
+    group = { name: groupName, tags: [] };
+    groups.push(group);
+  } else if (group !== groups.at(-1)) {
+    throw new Error(`delegated navigation group ${groupName} must be the final x-tagGroups entry`);
+  }
+  const groupedTags = new Set(groups.flatMap((candidate) => candidate.tags ?? []));
+  for (const tagName of tagNames) {
+    if (groupedTags.has(tagName)) continue;
+    group.tags.push(tagName);
+    groupedTags.add(tagName);
+  }
+}
+
+function namespaceComponents(document, delegatedId) {
+  const result = structuredClone(document);
+  const prefix = pascal(delegatedId);
+  const names = new Map();
+  for (const kind of componentKinds) {
+    for (const name of Object.keys(result.components?.[kind] ?? {})) names.set(`${kind}/${name}`, `${prefix}${pascal(name)}`);
+  }
+  visit(result, (value, key, parent) => {
+    if ((key !== '$ref' && key !== '$dynamicRef') || typeof value !== 'string') return;
+    const match = /^#\/components\/([^/]+)\/(.+)$/.exec(value);
+    if (!match) return;
+    const kind = decodePointer(match[1]);
+    const name = decodePointer(match[2]);
+    const replacement = names.get(`${kind}/${name}`);
+    if (!replacement) throw new Error(`delegated component reference is unresolved: ${value}`);
+    parent[key] = `#/components/${encodePointer(kind)}/${encodePointer(replacement)}`;
+  });
+  for (const kind of componentKinds) {
+    const group = result.components?.[kind];
+    if (!group) continue;
+    result.components[kind] = Object.fromEntries(Object.entries(group).map(([name, component]) => [names.get(`${kind}/${name}`), component]));
+  }
+  return result;
+}
+
+function mergeSecurityScheme(document, delegatedDocument, delegated) {
+  const schemes = delegatedDocument.components?.securitySchemes;
+  const names = Object.keys(schemes ?? {});
+  if (names.length !== 1 || names[0] !== delegated.security_scheme) {
+    throw new Error(`delegated contract ${delegated.id} must own exactly the configured ${delegated.security_scheme} scheme`);
+  }
+  document.components.securitySchemes ??= {};
+  const scheme = schemes[delegated.security_scheme];
+  const existing = document.components.securitySchemes[delegated.security_scheme];
+  if (existing !== undefined && canonicalJSON(existing) !== canonicalJSON(scheme)) {
+    throw new Error(`delegated security scheme collision: ${delegated.security_scheme}`);
+  }
+  document.components.securitySchemes[delegated.security_scheme] = structuredClone(scheme);
+  delete delegatedDocument.components.securitySchemes;
+}
+
+function validateOperation(operation, delegated, method, artifactPath, mountedPath) {
+  const label = `${method.toUpperCase()} ${mountedPath}`;
+  if (operation['x-onex-delegated-contract'] !== delegated.id) throw new Error(`${label} has no delegated contract identity`);
+  if (!operation['x-onex-owner']?.trim()) throw new Error(`${label} has no delegated owner`);
+  if (operation['x-onex-audience'] !== 'public' || operation['x-onex-stability'] !== 'stable') {
+    throw new Error(`${label} has invalid delegated publication metadata`);
+  }
+  if (
+    !Array.isArray(operation.security) ||
+    operation.security.length !== 1 ||
+    Object.keys(operation.security[0] ?? {}).length !== 1 ||
+    !Object.hasOwn(operation.security[0], delegated.security_scheme)
+  ) {
+    throw new Error(`${label} must require the configured ${delegated.security_scheme} scheme`);
+  }
+  const upstreamPath = operation['x-onex-upstream-path'];
+  const upstreamSecurity = operation['x-onex-upstream-security'];
+  const sourceOperationID = operation['x-onex-source-operation-id'];
+  if (typeof upstreamPath !== 'string' || !upstreamPath.startsWith('/') || typeof sourceOperationID !== 'string') {
+    throw new Error(`${label} has incomplete upstream lineage`);
+  }
+  if (!['anonymous', 'bearer_optional', 'bearer_required'].includes(upstreamSecurity)) {
+    throw new Error(`${label} has forbidden upstream security ${upstreamSecurity}`);
+  }
+  validatePathParameterBindings(
+    artifactPath,
+    upstreamPath,
+    operation['x-onex-path-parameter-bindings'],
+    label,
+  );
+  const csrf = delegated.csrf_protection;
+  const csrfRequired = csrf?.methods.includes(method.toUpperCase()) ?? false;
+  const csrfParameters = (operation.parameters ?? []).filter(
+    (parameter) => parameter?.in === 'header' && parameter?.name?.toLowerCase() === csrf?.header_name.toLowerCase(),
+  );
+  if (csrfParameters.length !== (csrfRequired ? 1 : 0)) throw new Error(`${label} has an invalid CSRF parameter contract`);
+}
+
+export function mountDelegatedPath(path, delegated) {
+  const mountedSuffix = stripConfiguredPrefix(path, delegated.source_path_prefixes_to_strip);
+  return `${delegated.mount_prefix}${mountedSuffix}`.replaceAll(/\/{2,}/g, '/');
+}
+
+function stripConfiguredPrefix(path, prefixes) {
+  for (const prefix of prefixes) {
+    if (path === prefix) return '/';
+    if (path.startsWith(`${prefix}/`)) return path.slice(prefix.length);
+  }
+  return path;
+}
+
+function applyCSRFProtection(operation, delegated, method, path) {
+  const csrf = delegated.csrf_protection;
+  if (!csrf?.methods.includes(method.toUpperCase())) return;
+  const parameters = operation.parameters ?? [];
+  if (!Array.isArray(parameters)) throw new Error(`${method.toUpperCase()} ${path} parameters must be an array`);
+  if (parameters.some((parameter) => parameter?.in === 'header' && parameter?.name?.toLowerCase() === csrf.header_name.toLowerCase())) {
+    throw new Error(`${method.toUpperCase()} ${path} already declares the configured CSRF header`);
+  }
+  operation.parameters = [...parameters, {
+    description: '跨站请求伪造防护令牌。',
+    in: 'header',
+    name: csrf.header_name,
+    required: true,
+    schema: { maxLength: 256, minLength: 32, type: 'string' },
+  }];
+}
+
+function validatePathParameterBindings(callerPath, sourcePath, bindings, label) {
+  if (bindings === null || typeof bindings !== 'object' || Array.isArray(bindings)) {
+    throw new Error(`${label} has an invalid path parameter binding contract`);
+  }
+  const callerNames = pathParameterNames(callerPath);
+  const sourceNames = pathParameterNames(sourcePath);
+  const bindingNames = Object.keys(bindings);
+  const boundSourceNames = Object.values(bindings);
+  if (
+    new Set(callerNames).size !== callerNames.length ||
+    new Set(sourceNames).size !== sourceNames.length ||
+    new Set(boundSourceNames).size !== boundSourceNames.length ||
+    callerNames.length !== sourceNames.length ||
+    bindingNames.length !== callerNames.length ||
+    callerNames.some((name) => typeof bindings[name] !== 'string') ||
+    sourceNames.some((name) => !boundSourceNames.includes(name))
+  ) {
+    throw new Error(`${label} path parameters must be bound exactly once`);
+  }
+}
+
+function pathParameterNames(path) {
+  return [...path.matchAll(/\{([A-Za-z][A-Za-z0-9_]*)\}/g)].map((match) => match[1]);
+}
+
+function visit(value, callback) {
+  if (Array.isArray(value)) {
+    for (const item of value) visit(item, callback);
+    return;
+  }
+  if (value === null || typeof value !== 'object') return;
+  for (const [key, child] of Object.entries(value)) {
+    callback(child, key, value);
+    visit(child, callback);
+  }
+}
+
+function pascal(value) {
+  return String(value).split(/[^A-Za-z0-9]+/).filter(Boolean).map((word) => word[0].toUpperCase() + word.slice(1)).join('');
+}
+
+function encodePointer(value) {
+  return String(value).replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function decodePointer(value) {
+  return String(value).replaceAll('~1', '/').replaceAll('~0', '~');
+}

package/dist/resources/templates/go-backend/api/openapi/tooling/deterministic_archive.mjs

@@ -0,0 +1,69 @@
+import { gzipSync } from 'node:zlib';
+
+const blockSize = 512;
+
+export function createDeterministicTGZ(files) {
+  const blocks = [];
+  for (const [relativePath, content] of [...files.entries()].sort(([left], [right]) => compareText(left, right))) {
+    const path = `package/${relativePath.replaceAll('\\', '/')}`;
+    const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    blocks.push(tarHeader(path, bytes.byteLength), bytes, Buffer.alloc(padding(bytes.byteLength)));
+  }
+  blocks.push(Buffer.alloc(blockSize * 2));
+  return gzipSync(Buffer.concat(blocks), { level: 9, mtime: 0 });
+}
+
+function tarHeader(path, size) {
+  const header = Buffer.alloc(blockSize);
+  const { name, prefix } = splitPath(path);
+  writeText(header, name, 0, 100);
+  writeOctal(header, 0o644, 100, 8);
+  writeOctal(header, 0, 108, 8);
+  writeOctal(header, 0, 116, 8);
+  writeOctal(header, size, 124, 12);
+  writeOctal(header, 0, 136, 12);
+  header.fill(0x20, 148, 156);
+  header[156] = '0'.charCodeAt(0);
+  writeText(header, 'ustar\0', 257, 6);
+  writeText(header, '00', 263, 2);
+  writeText(header, prefix, 345, 155);
+  const checksum = header.reduce((total, byte) => total + byte, 0);
+  const encoded = checksum.toString(8).padStart(6, '0');
+  writeText(header, encoded, 148, 6);
+  header[154] = 0;
+  header[155] = 0x20;
+  return header;
+}
+
+function splitPath(path) {
+  if (Buffer.byteLength(path) <= 100) return { name: path, prefix: '' };
+  for (let index = path.lastIndexOf('/'); index > 0; index = path.lastIndexOf('/', index - 1)) {
+    const prefix = path.slice(0, index);
+    const name = path.slice(index + 1);
+    if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) return { name, prefix };
+  }
+  throw new Error(`SDK archive path exceeds USTAR limits: ${path}`);
+}
+
+function writeText(buffer, value, offset, length) {
+  const bytes = Buffer.from(value, 'utf8');
+  if (bytes.byteLength > length) throw new Error(`USTAR field exceeds ${length} bytes: ${value}`);
+  bytes.copy(buffer, offset);
+}
+
+function writeOctal(buffer, value, offset, length) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`invalid USTAR numeric value: ${value}`);
+  const encoded = value.toString(8).padStart(length - 1, '0');
+  if (encoded.length >= length) throw new Error(`USTAR numeric value exceeds ${length} bytes: ${value}`);
+  writeText(buffer, `${encoded}\0`, offset, length);
+}
+
+function padding(size) {
+  return (blockSize - (size % blockSize)) % blockSize;
+}
+
+function compareText(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/dist/resources/templates/go-backend/api/openapi/tooling/documentation_example_privacy.mjs

@@ -0,0 +1,93 @@
+const sha256Patterns = new Set([
+  '^[a-f0-9]{64}$',
+  '^[0-9a-f]{64}$',
+  '^(?:|[a-f0-9]{64})$',
+  '^(?:|[0-9a-f]{64})$',
+]);
+
+export function isSensitiveExampleKey(value) {
+  const normalized = normalizeExampleKey(value);
+  if (/(^|_)token_(type|expires_at|expires_in)$/.test(normalized)) return false;
+  if (/^token_endpoint(?:_auth_methods_supported|_auth_signing_alg_values_supported)?$/.test(normalized)) return false;
+  return /(^|_)(password|secret|token|signature|api_key|apikey)($|_)/.test(normalized) ||
+    /(^|_)credential(s)?($|_(value|data|json)$)/.test(normalized);
+}
+
+export function isEmailExampleKey(value) {
+  const normalized = normalizeExampleKey(value);
+  return /^(email|email_address|from_address|reply_to_address)$/.test(normalized) ||
+    /_(email|email_address)$/.test(normalized);
+}
+
+export function safeSensitiveExampleValue(schema = {}) {
+  const candidates = [];
+  if (schema.format === 'uuid') candidates.push('00000000-0000-4000-8000-000000000000');
+  const sha256Value = safeSHA256ExampleValue(schema);
+  if (sha256Value !== null) candidates.push(sha256Value);
+  if (schema.pattern === '^[0-9]+$') candidates.push('0');
+
+  const boundedCharacterClass = boundedSensitivePatternExample(schema.pattern);
+  if (boundedCharacterClass !== null) candidates.push(boundedCharacterClass);
+
+  const literalPrefix = /^\^([A-Za-z0-9_.:-]+)/.exec(schema.pattern ?? '');
+  if (literalPrefix) candidates.push(`${literalPrefix[1]}redacted`);
+
+  candidates.push(fitLength('redacted-value', schema));
+  return candidates.find((candidate) => matchesStringSchema(candidate, schema)) ?? null;
+}
+
+export function safeSHA256ExampleValue(schema = {}) {
+  if (!sha256Patterns.has(schema.pattern)) return null;
+  const candidate = '0'.repeat(64);
+  return matchesStringSchema(candidate, schema) ? candidate : null;
+}
+
+export function isSafeSensitiveExampleValue(value, schema = {}) {
+  return value === safeSensitiveExampleValue(schema);
+}
+
+function boundedSensitivePatternExample(pattern) {
+  const match = /^\^([A-Za-z0-9_.:-]*)\[([A-Za-z0-9_-]+)\]\{([1-9][0-9]*)(?:,([1-9][0-9]*))?\}\$$/.exec(pattern ?? '');
+  if (!match) return null;
+  const minimum = Number(match[3]);
+  const maximum = Number(match[4] ?? match[3]);
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || minimum > maximum || minimum > 256) {
+    return null;
+  }
+  for (const character of ['0', 'a', 'A', '_', '-']) {
+    const candidate = `${match[1]}${character.repeat(minimum)}`;
+    if (matchesPattern(pattern, candidate)) return candidate;
+  }
+  return null;
+}
+
+function fitLength(value, schema) {
+  const minimum = schema.minLength ?? 0;
+  let candidate = value;
+  while (candidate.length < minimum) candidate += 'x';
+  if (Number.isInteger(schema.maxLength) && candidate.length > schema.maxLength) {
+    candidate = candidate.slice(0, schema.maxLength);
+  }
+  return candidate;
+}
+
+function matchesStringSchema(value, schema) {
+  if (Number.isInteger(schema.minLength) && value.length < schema.minLength) return false;
+  if (Number.isInteger(schema.maxLength) && value.length > schema.maxLength) return false;
+  return !schema.pattern || matchesPattern(schema.pattern, value);
+}
+
+function matchesPattern(pattern, value) {
+  try {
+    return new RegExp(pattern, 'u').test(value);
+  } catch {
+    return false;
+  }
+}
+
+function normalizeExampleKey(value) {
+  return String(value ?? '')
+    .replaceAll(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replaceAll(/[-.]/g, '_')
+    .toLowerCase();
+}