@simplexable/kc2-client 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplexable/kc2-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Host-neutral KC2 contracts for platform integrations.",
   "main": "./src/index.js",
   "type": "commonjs",
@@ -24,6 +24,7 @@
     "./authority/authorityContracts": "./src/authority/authorityContracts.js",
     "./authority/humanGuidanceContracts": "./src/authority/humanGuidanceContracts.js",
     "./authority/authorityDispositionContracts": "./src/authority/authorityDispositionContracts.js",
+    "./protectedContent/protectedContentReadinessContract": "./src/protectedContent/protectedContentReadinessContract.js",
     "./persistence/kc2WireOperationContracts": "./src/persistence/kc2WireOperationContracts.js",
     "./persistence/kc2GenerationSnapshotPersistenceContract": "./src/persistence/kc2GenerationSnapshotPersistenceContract.js",
     "./persistence/kc2HumanAuthorityReadContract": "./src/persistence/kc2HumanAuthorityReadContract.js",

package/src/index.js

@@ -29,6 +29,9 @@ module.exports = {
     authorityDispositionContracts: require('./authority/authorityDispositionContracts'),
     humanGuidanceContracts: require('./authority/humanGuidanceContracts'),
   },
+  protectedContent: {
+    protectedContentReadinessContract: require('./protectedContent/protectedContentReadinessContract'),
+  },
   persistence: {
     kc2WireOperationContracts: require('./persistence/kc2WireOperationContracts'),
     kc2GenerationSnapshotPersistenceContract: require('./persistence/kc2GenerationSnapshotPersistenceContract'),

package/src/protectedContent/protectedContentReadinessContract.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const CONTRACT_VERSION = 'protected-content-readiness.v1';
+const OPERATION = 'protected-content-readiness';
+const MAX_STRING_LENGTH = 512;
+const MAX_REASONS = 16;
+
+const OUTCOMES = Object.freeze([
+  'ready-for-adoption',
+  'ready-for-human-decision',
+  'blocked-recovery',
+  'blocked-repository-changed',
+  'blocked-authority-context-changed',
+  'blocked-protection-changed',
+  'blocked-candidate-invalid',
+  'blocked-addendum-duplication',
+  'unavailable',
+]);
+
+const BLOCKING_REASON_CODES = Object.freeze([
+  'inspection-artifact-unavailable',
+  'fingerprint-unavailable',
+  'authority-context-fingerprint-changed',
+  'repository-fingerprint-changed',
+  'candidate-fingerprint-changed',
+  'candidate-fingerprint-unavailable',
+  'candidate-facts-unavailable',
+  'human-authority-context-failed',
+  'human-authority-context-unavailable',
+  'protection-facts-unavailable',
+  'protection-not-current',
+  'protection-identity-changed',
+  'protection-not-active',
+  'addendum-facts-unavailable',
+  'addendum-duplication-observed',
+  'human-decision-pending',
+]);
+
+const HUMAN_AUTHORITY_CONTEXT_OUTCOMES = Object.freeze([
+  'success',
+  'failed',
+  'not-applicable',
+]);
+
+const LEGACY_REJECTED_REQUEST_KEYS = Object.freeze([
+  'blockingReasons',
+  'humanAuthorityContextStatus',
+  'humanAuthorityContextSuccess',
+  'dispositionOverallOutcome',
+  'authorityCurrent',
+  'repositoryCurrent',
+  'protectionCurrent',
+  'candidateValid',
+  'addendumValid',
+]);
+
+const ERROR_CATEGORIES = Object.freeze([
+  'invalid-payload',
+  'unauthorized',
+  'unavailable',
+  'unsupported-operation',
+  'semantic-failure',
+]);
+
+const ERROR_CODES = Object.freeze([
+  'invalid-payload',
+  'unauthorized',
+  'provider-unavailable',
+  'unsupported-operation',
+  'semantic-failure',
+]);
+
+function contractError(message) {
+  const error = new TypeError(message);
+  error.code = 'invalid-payload';
+  return error;
+}
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw contractError(`${label} must be an object`);
+  }
+}
+
+function assertNoUnknownKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw contractError(`${label}.${key} is not supported`);
+  }
+}
+
+function assertString(value, label, { nullable = false } = {}) {
+  if (nullable && value === null) return;
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_STRING_LENGTH) {
+    throw contractError(`${label} must be a bounded non-empty string${nullable ? ' or null' : ''}`);
+  }
+}
+
+function assertBoolean(value, label) {
+  if (typeof value !== 'boolean') throw contractError(`${label} must be boolean`);
+}
+
+function assertEnum(value, values, label) {
+  if (typeof value !== 'string' || !values.includes(value)) {
+    throw contractError(`${label} is not a supported value`);
+  }
+}
+
+function assertLegacyRejectedKeys(input, label) {
+  for (const key of LEGACY_REJECTED_REQUEST_KEYS) {
+    if (Object.hasOwn(input, key)) {
+      throw contractError(`${label}.${key} is not supported`);
+    }
+  }
+}
+
+function validateProtectionObserved(value, label) {
+  assertPlainObject(value, label);
+  assertNoUnknownKeys(value, ['present', 'active', 'protectionId', 'targetIdentity'], label);
+  assertBoolean(value.present, `${label}.present`);
+  if (Object.hasOwn(value, 'active')) assertBoolean(value.active, `${label}.active`);
+  if (Object.hasOwn(value, 'protectionId') && value.protectionId !== null) {
+    assertString(value.protectionId, `${label}.protectionId`);
+  }
+  if (Object.hasOwn(value, 'targetIdentity') && value.targetIdentity !== null) {
+    assertString(value.targetIdentity, `${label}.targetIdentity`);
+  }
+}
+
+function validateProtectedContentReadinessRequest(input) {
+  assertPlainObject(input, 'request');
+  assertLegacyRejectedKeys(input, 'request');
+  assertNoUnknownKeys(input, [
+    'contractVersion',
+    'platformId',
+    'articleKey',
+    'inspectionAvailable',
+    'blockingRecovery',
+    'persistedAuthorityFingerprint',
+    'observedAuthorityFingerprint',
+    'persistedRepositoryFingerprint',
+    'observedRepositoryFingerprint',
+    'persistedCandidateFingerprint',
+    'observedCandidateFingerprint',
+    'protectionObserved',
+    'protectionInspectedId',
+    'humanAuthorityContextOutcome',
+    'addendumPresent',
+    'addendumDuplicateLikely',
+    'humanDecisionPending',
+    'requestId',
+  ], 'request');
+  if (input.contractVersion !== CONTRACT_VERSION) {
+    throw contractError('request.contractVersion is unsupported');
+  }
+  assertString(input.platformId, 'request.platformId');
+  assertString(input.articleKey, 'request.articleKey');
+  assertBoolean(input.inspectionAvailable, 'request.inspectionAvailable');
+  if (Object.hasOwn(input, 'blockingRecovery')) {
+    assertBoolean(input.blockingRecovery, 'request.blockingRecovery');
+  }
+  for (const key of [
+    'persistedAuthorityFingerprint',
+    'observedAuthorityFingerprint',
+    'persistedRepositoryFingerprint',
+    'observedRepositoryFingerprint',
+    'persistedCandidateFingerprint',
+    'observedCandidateFingerprint',
+    'protectionInspectedId',
+  ]) {
+    if (Object.hasOwn(input, key)) assertString(input[key], `request.${key}`);
+  }
+  if (Object.hasOwn(input, 'protectionObserved')) {
+    validateProtectionObserved(input.protectionObserved, 'request.protectionObserved');
+  }
+  if (Object.hasOwn(input, 'humanAuthorityContextOutcome')) {
+    assertEnum(
+      input.humanAuthorityContextOutcome,
+      HUMAN_AUTHORITY_CONTEXT_OUTCOMES,
+      'request.humanAuthorityContextOutcome',
+    );
+  }
+  if (Object.hasOwn(input, 'addendumPresent')) {
+    assertBoolean(input.addendumPresent, 'request.addendumPresent');
+  }
+  if (Object.hasOwn(input, 'addendumDuplicateLikely')) {
+    assertBoolean(input.addendumDuplicateLikely, 'request.addendumDuplicateLikely');
+  }
+  if (Object.hasOwn(input, 'humanDecisionPending')) {
+    assertBoolean(input.humanDecisionPending, 'request.humanDecisionPending');
+  }
+  if (Object.hasOwn(input, 'requestId') && input.requestId !== null) {
+    assertString(input.requestId, 'request.requestId');
+  }
+  return input;
+}
+
+function validateProtectedContentReadinessResponse(input) {
+  assertPlainObject(input, 'response');
+  assertNoUnknownKeys(input, [
+    'contractVersion',
+    'success',
+    'operation',
+    'provider',
+    'result',
+    'error',
+  ], 'response');
+  if (input.contractVersion !== CONTRACT_VERSION) {
+    throw contractError('response.contractVersion is unsupported');
+  }
+  assertBoolean(input.success, 'response.success');
+  if (input.operation !== OPERATION) throw contractError('response.operation is unsupported');
+  assertPlainObject(input.provider, 'response.provider');
+  assertNoUnknownKeys(input.provider, ['providerId', 'providerVersion'], 'response.provider');
+  assertString(input.provider.providerId, 'response.provider.providerId');
+  assertString(input.provider.providerVersion, 'response.provider.providerVersion');
+  if (input.success) {
+    if (input.error !== null) throw contractError('response.error must be null on success');
+    assertPlainObject(input.result, 'response.result');
+    assertNoUnknownKeys(input.result, ['outcome', 'blockingReasonCodes'], 'response.result');
+    assertEnum(input.result.outcome, OUTCOMES, 'response.result.outcome');
+    if (!Array.isArray(input.result.blockingReasonCodes)
+      || input.result.blockingReasonCodes.length > MAX_REASONS) {
+      throw contractError('response.result.blockingReasonCodes must be a bounded array');
+    }
+    const seen = new Set();
+    input.result.blockingReasonCodes.forEach((reason, index) => {
+      assertEnum(reason, BLOCKING_REASON_CODES, `response.result.blockingReasonCodes[${index}]`);
+      if (seen.has(reason)) {
+        throw contractError(`response.result.blockingReasonCodes[${index}] is duplicated`);
+      }
+      seen.add(reason);
+    });
+  } else if (input.error !== null) {
+    assertPlainObject(input.error, 'response.error');
+    assertNoUnknownKeys(input.error, ['category', 'code', 'message'], 'response.error');
+    assertEnum(input.error.category, ERROR_CATEGORIES, 'response.error.category');
+    assertEnum(input.error.code, ERROR_CODES, 'response.error.code');
+    assertString(input.error.message, 'response.error.message');
+  }
+  return input;
+}
+
+function normalizeProtectedContentReadinessRequest(input) {
+  return validateProtectedContentReadinessRequest(input);
+}
+
+function normalizeProtectedContentReadinessResponse(input) {
+  return validateProtectedContentReadinessResponse(input);
+}
+
+module.exports = {
+  BLOCKING_REASON_CODES,
+  CONTRACT_VERSION,
+  ERROR_CATEGORIES,
+  ERROR_CODES,
+  HUMAN_AUTHORITY_CONTEXT_OUTCOMES,
+  LEGACY_REJECTED_REQUEST_KEYS,
+  MAX_REASONS,
+  MAX_STRING_LENGTH,
+  OPERATION,
+  OUTCOMES,
+  normalizeProtectedContentReadinessRequest,
+  normalizeProtectedContentReadinessResponse,
+  validateProtectedContentReadinessRequest,
+  validateProtectedContentReadinessResponse,
+};