@matuto-ai/opencode-psst-connector 0.0.0-stage → 0.7.0

package/vendor/broker/src/protocol.mjs

@@ -0,0 +1,325 @@
+import { createHash } from 'node:crypto';
+
+export const TYPES = Object.freeze(['pi', 'antigravity-cli', 'claude-code', 'opencode']);
+export const DEFAULTS = Object.freeze({
+  heartbeat_seconds: 60, lease_seconds: 180, claim_seconds: 120, max_wait_seconds: 30,
+  offline_notice_seconds: 600,
+  default_ttl_seconds: 86400, min_ttl_seconds: 60, max_ttl_seconds: 604800,
+  max_message_bytes: 65536, max_request_bytes: 98304,
+  max_pending_messages: 1000, max_pending_bytes: 67108864,
+  send_per_minute: 60, send_burst: 20, max_attempts: 10,
+  retention_seconds: 604800, registration_retention_seconds: 86400,
+  retry_window_seconds: 86400,
+});
+
+const ERROR_TEXT = Object.freeze({
+  invalid_request: ['The request does not match the v1 contract.', 'Correct the indicated field before retrying.'],
+  unauthenticated: ['Authentication is required.', 'Use an enrolled credential through the Authorization header.'],
+  forbidden: ['This operation is not authorized.', 'Check the enrolled adapter permissions.'],
+  recipient_not_found: ['The recipient is not available.', 'Select an exact authorized client ID from discovery.'],
+  message_not_found: ['The message is not available.', 'Use a message ID owned by this principal.'],
+  retry_window_elapsed: ['The operation recovery record has expired.', 'Reconcile the existing receipt; only an explicit new send or resend may create another delivery.'],
+  history_changed: ['History changed while paging.', 'Restart the listing without a cursor; no continuation was silently skipped.'],
+  content_unavailable: ['The original content is no longer retained.', 'Use the receipt; unavailable content cannot be reconstructed.'],
+  identity_conflict: ['The session identity conflicts with an existing registration.', 'Do not adopt another session; verify the local session identity.'],
+  stale_lease_epoch: ['Reconnect this session before retrying.', 'Read owned registration state and reconnect; do not blindly replay a mutation.'],
+  idempotency_conflict: ['This key was already used for a different request.', 'Reconcile the original request; do not change an uncertain request.'],
+  metadata_conflict: ['The metadata revision changed.', 'Read the current revision and reconcile the metadata patch.'],
+  claim_conflict: ['The claim is not current.', 'Reconcile the claim before acknowledging or requesting another.'],
+  registration_upgrade_required: ['Registration v2 is required.', 'Update the connector; do not retry this registration with a new identity.'],
+  session_closed: ['This session is closed.', 'Create a new identity only for a new harness session.'],
+  message_expired: ['The message transport deadline passed.', 'Read the receipt; expiry does not retract an accepted inbox item.'],
+  payload_too_large: ['The request exceeds a byte or item limit.', 'Reduce the indicated field before retrying.'],
+  incompatible_receiver_transport: ['The recipient does not support this durable-inbox transport.', 'Choose a compatible recipient or update its adapter.'],
+  receiving_disabled: ['The recipient has disabled transport receiving.', 'Wait for the recipient operator to enable receiving.'],
+  rate_limited: ['The request rate limit was reached.', 'Honor Retry-After; reuse the same key for an uncertain request.'],
+  mailbox_full: ['The destination mailbox is full.', 'Honor Retry-After; do not discard or duplicate an uncertain send.'],
+  storage_unavailable: ['Durable storage is unavailable.', 'Restore storage health; retry only with the original idempotency key.'],
+  not_ready: ['The broker is not ready.', 'Wait for readiness; retry only idempotent operations.'],
+});
+
+function contractReference(field) {
+  if (field === 'headers.X-Lease-Epoch') return 'openapi.json#/components/parameters/LeaseEpoch';
+  if (field === 'headers.X-Client-ID') return 'openapi.json#/components/parameters/ClientId';
+  if (field === 'headers.Idempotency-Key') return 'openapi.json#/components/parameters/IdempotencyKey';
+  return 'openapi.json#/components/schemas/Error';
+}
+
+export class ApiError extends Error {
+  constructor(status, code, field = null, options = {}) {
+    const text = ERROR_TEXT[code] ?? ERROR_TEXT.invalid_request;
+    super(options.message ?? text[0]);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+    this.field = field;
+    this.retryable = options.retryable ?? [429, 503].includes(status);
+    this.effect = options.effect ?? 'not_applied';
+    this.action = options.action ?? text[1];
+    this.contract_ref = options.contract_ref ?? contractReference(field);
+    this.retry_after = options.retry_after;
+    this.details = options.details;
+  }
+
+  toJSON(requestId) {
+    const error = {
+      code: this.code, message: this.message, retryable: this.retryable,
+      field: this.field, contract_ref: this.contract_ref, action: this.action,
+      effect: this.effect, request_id: requestId ?? null,
+    };
+    if (this.details !== undefined) error.details = this.details;
+    return { error };
+  }
+}
+
+function invalid(field, code = 'invalid_request', status = 400) {
+  throw new ApiError(status, code, field);
+}
+
+function object(value, allowed, required, path) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) invalid(path);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) invalid(path);
+  for (const key of required) if (!Object.hasOwn(value, key)) invalid(`${path}.${key}`);
+  return value;
+}
+
+function string(value, path, { maxChars = 256, maxBytes = maxChars * 4, minChars = 0, nullable = false, label = false } = {}) {
+  if (nullable && value === null) return null;
+  if (typeof value !== 'string' || !value.isWellFormed()) invalid(path);
+  const size = [...value].length;
+  if (size < minChars) invalid(path);
+  if (size > maxChars || Buffer.byteLength(value, 'utf8') > maxBytes) invalid(path, 'payload_too_large', 413);
+  if (label && /[\u0000-\u001f\u007f-\u009f]/u.test(value)) invalid(path);
+  return value;
+}
+
+function integer(value, min, max, path) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) invalid(path);
+  return value;
+}
+
+function boolean(value, path) {
+  if (typeof value !== 'boolean') invalid(path);
+  return value;
+}
+
+function oneOf(value, values, path) {
+  if (!values.includes(value)) invalid(path);
+  return value;
+}
+
+export function validateUuid(value, path = 'id') {
+  if (typeof value !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) invalid(path);
+  return value.toLowerCase();
+}
+
+export function validateIdempotencyKey(value, path = 'headers.Idempotency-Key') {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9._~:+\/-]{1,128}$/.test(value)) invalid(path);
+  return value;
+}
+
+function model(value, path) {
+  object(value, ['provider', 'id', 'source'], ['provider', 'id', 'source'], path);
+  const result = {
+    provider: string(value.provider, `${path}.provider`, { maxChars: 128, nullable: true, label: true }),
+    id: string(value.id, `${path}.id`, { maxChars: 256, nullable: true, label: true }),
+    source: oneOf(value.source, ['observed', 'configured', 'unknown'], `${path}.source`),
+  };
+  if (result.source === 'unknown' && (result.id !== null || result.provider !== null)) invalid(path);
+  return result;
+}
+
+export function validateMetadata(value, { patch = false, path = 'body.metadata' } = {}) {
+  object(value, ['name', 'model', 'project'], patch ? [] : ['name', 'model', 'project'], path);
+  if (patch && Object.keys(value).length === 0) invalid(path);
+  const result = {};
+  if (Object.hasOwn(value, 'name')) result.name = string(value.name, `${path}.name`, { maxChars: 128, minChars: 1, label: true });
+  if (Object.hasOwn(value, 'model')) result.model = model(value.model, `${path}.model`);
+  if (Object.hasOwn(value, 'project')) result.project = string(value.project, `${path}.project`, { maxChars: 256, nullable: true, label: true });
+  return result;
+}
+
+export function validateRegistration(value) {
+  const fields = ['protocol_version', 'client_id', 'client_type', 'session_instance_id', 'connection_id', 'previous_epoch', 'metadata', 'capabilities'];
+  object(value, [...fields, 'registration_version', 'requested_at'], fields, 'body');
+  const version = value.registration_version ?? 1;
+  integer(version, 1, 2, 'body.registration_version');
+  if (version === 1 && value.requested_at !== undefined) invalid('body.requested_at');
+  const freshness = version === 2 ? { registration_version: 2, requested_at: integer(value.requested_at, 0, Number.MAX_SAFE_INTEGER, 'body.requested_at') } : {};
+  const type = oneOf(value.client_type, TYPES, 'body.client_type');
+  const c = object(value.capabilities, ['protocol_version', 'adapter_version', 'client_type', 'receive_enabled', 'durable_inbox'], ['protocol_version', 'adapter_version', 'client_type', 'receive_enabled', 'durable_inbox'], 'body.capabilities');
+  if (c.client_type !== type) invalid('body.capabilities.client_type');
+  return {
+    ...freshness,
+    protocol_version: oneOf(value.protocol_version, ['1'], 'body.protocol_version'),
+    client_id: validateUuid(value.client_id, 'body.client_id'),
+    client_type: type,
+    session_instance_id: validateUuid(value.session_instance_id, 'body.session_instance_id'),
+    connection_id: validateUuid(value.connection_id, 'body.connection_id'),
+    previous_epoch: integer(value.previous_epoch, 0, Number.MAX_SAFE_INTEGER - 1, 'body.previous_epoch'),
+    metadata: validateMetadata(value.metadata),
+    capabilities: {
+      protocol_version: oneOf(c.protocol_version, ['1'], 'body.capabilities.protocol_version'),
+      adapter_version: string(c.adapter_version, 'body.capabilities.adapter_version', { maxChars: 128, minChars: 1, label: true }),
+      client_type: type,
+      receive_enabled: boolean(c.receive_enabled, 'body.capabilities.receive_enabled'),
+      durable_inbox: boolean(c.durable_inbox, 'body.capabilities.durable_inbox'),
+    },
+  };
+}
+
+export function validateMetadataPatch(value) {
+  object(value, ['metadata_patch', 'expected_metadata_revision'], ['metadata_patch', 'expected_metadata_revision'], 'body');
+  return {
+    metadata_patch: validateMetadata(value.metadata_patch, { patch: true, path: 'body.metadata_patch' }),
+    expected_metadata_revision: integer(value.expected_metadata_revision, 1, Number.MAX_SAFE_INTEGER, 'body.expected_metadata_revision'),
+  };
+}
+
+function content(value, path, limits = DEFAULTS) {
+  object(value, ['type', 'text'], ['type', 'text'], path);
+  return {
+    type: oneOf(value.type, ['text/plain'], `${path}.type`),
+    text: string(value.text, `${path}.text`, { maxChars: Math.min(DEFAULTS.max_message_bytes, limits.max_message_bytes), maxBytes: Math.min(DEFAULTS.max_message_bytes, limits.max_message_bytes) }),
+  };
+}
+
+export function validateSend(value, { limits: configured = DEFAULTS } = {}) {
+  const limits = { ...DEFAULTS, ...configured };
+  object(value, ['recipient_id', 'content', 'ttl_seconds', 'correlation_id', 'reply_to_message_id', 'metadata_patch', 'expected_metadata_revision'], ['recipient_id', 'content'], 'body');
+  const result = {
+    recipient_id: validateUuid(value.recipient_id, 'body.recipient_id'),
+    content: content(value.content, 'body.content', limits),
+    ttl_seconds: integer(value.ttl_seconds ?? limits.default_ttl_seconds, Math.max(DEFAULTS.min_ttl_seconds, limits.min_ttl_seconds), Math.min(DEFAULTS.max_ttl_seconds, limits.max_ttl_seconds), 'body.ttl_seconds'),
+    correlation_id: string(value.correlation_id ?? null, 'body.correlation_id', { maxChars: 128, maxBytes: 512, nullable: true }),
+    reply_to_message_id: value.reply_to_message_id == null ? null : validateUuid(value.reply_to_message_id, 'body.reply_to_message_id'),
+  };
+  if (Object.hasOwn(value, 'ttl_seconds') && value.ttl_seconds === null) invalid('body.ttl_seconds');
+  if (Object.hasOwn(value, 'metadata_patch')) {
+    if (!Object.hasOwn(value, 'expected_metadata_revision')) invalid('body.expected_metadata_revision');
+    result.metadata_patch = validateMetadata(value.metadata_patch, { patch: true, path: 'body.metadata_patch' });
+    result.expected_metadata_revision = integer(value.expected_metadata_revision, 1, Number.MAX_SAFE_INTEGER, 'body.expected_metadata_revision');
+  } else if (Object.hasOwn(value, 'expected_metadata_revision')) invalid('body.expected_metadata_revision');
+  return result;
+}
+
+export function validateClaim(value, { limits: configured = DEFAULTS } = {}) {
+  const limits = { ...DEFAULTS, ...configured };
+  object(value, ['wait_seconds'], [], 'body');
+  return { wait_seconds: integer(Object.hasOwn(value, 'wait_seconds') ? value.wait_seconds : 0, 0, Math.min(DEFAULTS.max_wait_seconds, limits.max_wait_seconds), 'body.wait_seconds') };
+}
+
+export function validateRenew(value) {
+  object(value, ['claim_id'], ['claim_id'], 'body');
+  return { claim_id: validateUuid(value.claim_id, 'body.claim_id') };
+}
+
+export function validateCompletion(value) {
+  object(value, ['claim_id', 'outcome', 'reason'], ['claim_id', 'outcome'], 'body');
+  const outcome = oneOf(value.outcome, ['delivered', 'retryable_not_stored', 'permanent_not_stored'], 'body.outcome');
+  const reason = oneOf(value.reason ?? 'none', ['none', 'inbox_full', 'storage_unavailable', 'unsupported_envelope'], 'body.reason');
+  if (Object.hasOwn(value, 'reason') && value.reason === null) invalid('body.reason');
+  if (outcome === 'delivered' && reason !== 'none') invalid('body.reason');
+  return { claim_id: validateUuid(value.claim_id, 'body.claim_id'), outcome, reason };
+}
+
+export function validateEmpty(value) {
+  object(value, [], [], 'body');
+  return {};
+}
+
+function timestamp(value, path) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value) || !Number.isFinite(Date.parse(value))) invalid(path);
+  const normalized = new Date(Date.parse(value)).toISOString();
+  if (normalized !== (value.includes('.') ? value : value.replace('Z', '.000Z'))) invalid(path);
+  return value;
+}
+
+export function validateEnvelope(value) {
+  const fields = ['protocol_version', 'message_id', 'recipient_id', 'recipient_sequence', 'sender', 'origin', 'authority', 'content', 'accepted_at', 'expires_at', 'correlation_id', 'reply_to_message_id'];
+  object(value, fields, fields, 'envelope');
+  object(value.sender, ['client_id', 'client_type', 'name', 'model', 'project', 'metadata_revision'], ['client_id', 'client_type', 'name', 'model', 'project', 'metadata_revision'], 'envelope.sender');
+  const meta = validateMetadata({ name: value.sender.name, model: value.sender.model, project: value.sender.project }, { path: 'envelope.sender' });
+  const acceptedAt = timestamp(value.accepted_at, 'envelope.accepted_at');
+  const expiresAt = timestamp(value.expires_at, 'envelope.expires_at');
+  if (Date.parse(expiresAt) <= Date.parse(acceptedAt)) invalid('envelope.expires_at');
+  return {
+    protocol_version: oneOf(value.protocol_version, ['1'], 'envelope.protocol_version'),
+    message_id: validateUuid(value.message_id, 'envelope.message_id'),
+    recipient_id: validateUuid(value.recipient_id, 'envelope.recipient_id'),
+    recipient_sequence: integer(value.recipient_sequence, 1, Number.MAX_SAFE_INTEGER, 'envelope.recipient_sequence'),
+    sender: { client_id: validateUuid(value.sender.client_id, 'envelope.sender.client_id'), client_type: oneOf(value.sender.client_type, TYPES, 'envelope.sender.client_type'), ...meta, metadata_revision: integer(value.sender.metadata_revision, 1, Number.MAX_SAFE_INTEGER, 'envelope.sender.metadata_revision') },
+    origin: oneOf(value.origin, ['broker_agent'], 'envelope.origin'),
+    authority: oneOf(value.authority, ['untrusted_agent_input'], 'envelope.authority'),
+    content: content(value.content, 'envelope.content'),
+    accepted_at: acceptedAt, expires_at: expiresAt,
+    correlation_id: string(value.correlation_id, 'envelope.correlation_id', { maxChars: 128, maxBytes: 512, nullable: true }),
+    reply_to_message_id: value.reply_to_message_id === null ? null : validateUuid(value.reply_to_message_id, 'envelope.reply_to_message_id'),
+  };
+}
+
+/**
+ * v1 canonical JSON: recursively sort object keys by UTF-16 code units, serialize
+ * primitives with JSON.stringify, preserve array order, and encode as UTF-8.
+ * No Unicode normalization. Reject non-JSON values, malformed Unicode, cycles,
+ * excessive nesting, unsafe/nonfinite numbers, and sparse arrays.
+ */
+export function canonical(value) {
+  const ancestors = new Set();
+  function visit(item, depth) {
+    if (depth > 32) invalid('canonical.depth');
+    if (item === null || typeof item === 'boolean') return JSON.stringify(item);
+    if (typeof item === 'string') {
+      if (!item.isWellFormed()) invalid('canonical.string');
+      return JSON.stringify(item);
+    }
+    if (typeof item === 'number') {
+      if (!Number.isFinite(item) || (Number.isInteger(item) && !Number.isSafeInteger(item))) invalid('canonical.number');
+      return JSON.stringify(item);
+    }
+    if (typeof item !== 'object' || ancestors.has(item)) invalid('canonical.value');
+    ancestors.add(item);
+    let result;
+    if (Array.isArray(item)) {
+      if (item.length > 10000) invalid('canonical.array');
+      const parts = [];
+      for (let i = 0; i < item.length; i++) {
+        if (!Object.hasOwn(item, i)) invalid('canonical.array');
+        parts.push(visit(item[i], depth + 1));
+      }
+      result = `[${parts.join(',')}]`;
+    } else {
+      if (![Object.prototype, null].includes(Object.getPrototypeOf(item))) invalid('canonical.object');
+      const keys = Object.keys(item).sort();
+      if (keys.length > 10000) invalid('canonical.object');
+      result = `{${keys.map((key) => {
+        if (!key.isWellFormed()) invalid('canonical.key');
+        return `${JSON.stringify(key)}:${visit(item[key], depth + 1)}`;
+      }).join(',')}}`;
+    }
+    ancestors.delete(item);
+    return result;
+  }
+  return visit(value, 0);
+}
+
+export function digest(value) {
+  return createHash('sha256').update(canonical(value), 'utf8').digest('hex');
+}
+
+export function validateResend(value, { limits = {} } = {}) {
+  object(value, ['ttl_seconds'], [], 'body');
+  const merged = { ...DEFAULTS, ...limits };
+  return { ttl_seconds: value.ttl_seconds === undefined ? merged.default_ttl_seconds : integer(value.ttl_seconds, Math.max(60, merged.min_ttl_seconds), Math.min(604800, merged.max_ttl_seconds), 'body.ttl_seconds') };
+}
+
+/** New internal keys carry a timestamp; legacy keys retain their bounded v1 guarantee. */
+export function validateOperationTime(key, now, retryWindowSeconds) {
+  if(!key.startsWith('op_'))return;
+  const match=/^op_([0-9]{13})_([A-Za-z0-9_-]{16,96})$/.exec(key);
+  if(!match)throw new ApiError(400,'invalid_request','headers.Idempotency-Key');
+  const started=Number(match[1]);
+  if(started>now+300000)throw new ApiError(400,'invalid_request','headers.Idempotency-Key');
+  if(now-started>=retryWindowSeconds*1000)throw new ApiError(410,'retry_window_elapsed','headers.Idempotency-Key');
+}

package/vendor/enrollment/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Orsolon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/enrollment/ORIGIN.md

@@ -0,0 +1,20 @@
+# Shared enrollment helper
+
+Unmodified `reference/enrollment.mjs` from `matuto-ai/psst` commit `3e908e79966d886a02d372c103e31dec6e900c1a`, independently compared byte-for-byte with the remote committed source. Upstream PR #18 is pending review/merge; this commit pin is not a deployment or release claim.
+
+SHA-256: `afeab00d7c2d6768d3537bd7c350e249768897bf81eff9b4ae9796f7c3f9dbe9`.
+
+Runtime hash checked by `src/enrollment.mjs` before import. MIT license copied alongside. The existing pinned broker transport/runtime remains unchanged at its separate origin.
+
+Source: https://github.com/matuto-ai/psst/blob/3e908e79966d886a02d372c103e31dec6e900c1a/reference/enrollment.mjs
+Operator guide at that commit: https://github.com/matuto-ai/psst/blob/3e908e79966d886a02d372c103e31dec6e900c1a/docs/pairing-operator.md
+
+## URL-only approval helper
+
+`approval.mjs` is vendored byte-for-byte from `matuto-ai/psst` commit
+`72f5d2d1b834e02cfb6b2f7dc11c6f1a55729344`, path `reference/approval.mjs`,
+Git blob `8e6128c22835e66c0ab50aa15c27ff16d33e1169`, SHA-256
+`a60c3a0ccd7deb50556586cd67841bb89a300ea3c7f1af3a91d437f856b7a2d5`.
+This is the explicit broker PR #22 dependency, not a claim of a deployed release.
+The connector checks the digest before importing it. The old enrollment helper
+remains unchanged for legacy bundles/receipts.

package/vendor/enrollment/approval.mjs

@@ -0,0 +1,181 @@
+// Single-file helper deliberately vendorable by native connectors. Never emits secrets.
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { openSync, closeSync, fstatSync, readFileSync, writeFileSync, fsyncSync, renameSync, unlinkSync, mkdirSync, lstatSync, realpathSync, readdirSync, constants } from 'node:fs';
+import { resolve, dirname, join, isAbsolute } from 'node:path';
+import https from 'node:https';
+import { DatabaseSync } from 'node:sqlite';
+
+const TYPES = ['pi','claude-code','opencode','antigravity-cli'];
+const fail = (code, effect = 'not_applied', retryable=false, retryAfterMs=2000) => { const e = new Error(code); Object.assign(e,{code,effect,retryable,...(retryable?{retryAfterMs:Math.max(1000,Math.min(300000,Math.ceil(retryAfterMs)))}:{})}); throw e; };
+const hash = value => createHash('sha256').update(value).digest('hex');
+function privateDir(path) {
+  if (!isAbsolute(path)) fail('private_directory_required');
+  mkdirSync(path, {recursive:true, mode:0o700});
+  const s = lstatSync(path);
+  if (!s.isDirectory() || s.isSymbolicLink() || realpathSync(path) !== resolve(path) || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid())) fail('private_directory_required');
+}
+function privateRead(path) {
+  if (!isAbsolute(path) || realpathSync(dirname(path)) !== resolve(dirname(path))) fail('private_file_required');
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || s.size > 65536 || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid())) fail('private_file_required');
+    return readFileSync(fd,'utf8');
+  } finally { closeSync(fd); }
+}
+function save(path, text) {
+  // Reject unsafe existing destinations rather than silently repairing their mode.
+  try { privateRead(path); } catch(e) { if(e.code !== 'ENOENT') throw e; }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temp, constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);
+  try { writeFileSync(fd,text); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temp,path);
+  const d = openSync(dirname(path),constants.O_RDONLY);try { fsyncSync(d); } finally { closeSync(d); }
+}
+function origin(value) {
+  let u; try { u = new URL(value); } catch { fail('https_origin_required'); }
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f]/u.test(value) || u.protocol !== 'https:' || u.username || u.password || u.pathname !== '/' || u.search || u.hash) fail('https_origin_required');
+  return u.origin;
+}
+const stateNames=['pending','approved','denied','expired','revoked'];
+const uuid=/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function locations({brokerUrl,directory,clientType}) {
+  if(!TYPES.includes(clientType))fail('invalid_client_type');
+  if(!isAbsolute(directory))fail('private_directory_required');
+  const broker=origin(brokerUrl),root=join(directory,'approvals',hash(broker+'\0'+clientType));
+  return {broker,root,current:join(root,'current.json'),clientType};
+}
+function load(loc) {
+  let pointer;try{pointer=JSON.parse(privateRead(loc.current));}catch(e){if(e.code==='ENOENT')return null;throw e;}
+  if(!pointer||!uuid.test(pointer.requestId))fail('invalid_approval_state');
+  const dir=join(loc.root,pointer.requestId),state=JSON.parse(privateRead(join(dir,'attempt.json')));
+  if(state.requestId!==pointer.requestId||state.brokerUrl!==loc.broker||state.clientType!==loc.clientType
+    ||!/^[A-Za-z0-9_-]{43}$/.test(state.token)||!stateNames.includes(state.state)
+    ||typeof state.label!=='string'||state.label.length>80)fail('invalid_approval_state');
+  return {state,dir};
+}
+function visible({state,dir}) {
+  const result={requestId:state.requestId,approvalUrl:state.brokerUrl+'/admin',state:state.state,requestExpiresAt:state.requestExpiresAt??null};
+  if(state.state==='approved'){
+    if(!state.credential||Date.parse(state.credential.expires_at)<=Date.now())return {...result,state:'expired'};
+    result.connectionFile=join(dir,'connection.json');
+    Object.assign(result,readEnrollmentReceipt({connectionFile:result.connectionFile,clientType:state.clientType}));
+  }
+  return result;
+}
+function sanitized(e) {
+  if(e.effect&&/^[a-z_]+$/.test(e.code))throw e;
+  fail('approval_local_error','unknown');
+}
+export function readApprovalState(options) {
+  try{const item=load(locations(options));return item?visible(item):null;}catch(e){sanitized(e);}
+}
+function request(broker,method,path,token,input) {
+  return new Promise((resolvePromise,reject)=>{
+    const body=input===undefined?undefined:JSON.stringify(input);
+    const transportError=()=>Object.assign(new Error('approval_transport_error'),{code:'approval_transport_error',effect:'unknown',retryable:true,retryAfterMs:2000});
+    const req=https.request(new URL(path,broker),{method,headers:{Authorization:`Enrollment ${token}`,...(body?{'Content-Type':'application/json','Content-Length':Buffer.byteLength(body)}:{})}},res=>{
+      let size=0;const chunks=[];
+      res.on('data',chunk=>{size+=chunk.length;if(size>16384)res.destroy();else chunks.push(chunk);});
+      res.on('error',()=>reject(transportError()));
+      res.on('end',()=>{try{resolvePromise({status:res.statusCode,retryAfter:res.headers['retry-after'],body:JSON.parse(Buffer.concat(chunks).toString('utf8'))});}catch{reject(Object.assign(new Error('invalid_response'),{code:'invalid_response',effect:'unknown',retryable:false}));}});
+    });
+    const timer=setTimeout(()=>req.destroy(),10000);req.on('close',()=>clearTimeout(timer));
+    req.on('error',()=>reject(transportError()));req.end(body);
+  });
+}
+function publish(item,result,broker,clientType){
+  const {state,dir}=item;
+  if(!result||result.request_id!==state.requestId||!stateNames.includes(result.state)
+    ||!Number.isFinite(Date.parse(result.request_expires_at)))fail('invalid_response','unknown');
+  if(result.state==='approved'){
+    const c=result.credential;
+    if(!c||c.protocol_version!=='1'||c.client_type!==clientType||!/^enrolled-[0-9a-f-]{36}$/.test(c.credential_id)
+      ||!/^installation-[0-9a-f-]{36}$/.test(c.adapter_id)||!Array.isArray(c.scopes)||!c.scopes.length||c.scopes.length>32
+      ||c.scopes.some(s=>typeof s!=='string'||!/^[-a-zA-Z0-9_.]{1,128}$/.test(s))||!Number.isFinite(Date.parse(c.expires_at)))fail('invalid_response','unknown');
+    if(Date.parse(c.expires_at)<=Date.now())fail('credential_expired');
+    save(join(dir,'token'),state.token+'\n');
+    save(join(dir,'enrollment.json'),JSON.stringify({format:'psst-enrollment-receipt-v1',broker_url:broker,...c,token_sha256:hash(state.token)})+'\n');
+    save(join(dir,'connection.json'),JSON.stringify({format:'broker-client-bundle-v1',protocol_version:'1',broker_url:broker,token_file:'token',enrollment_receipt_file:'enrollment.json',file_paths_relative_to:'connection_file_directory',authorization_header:'Authorization',authorization_scheme:'Bearer',insecure_development:false,allowed_client_types:[clientType],scope:c.scopes[0]})+'\n');
+    state.credential=c;
+  }
+  state.state=result.state;state.requestExpiresAt=result.request_expires_at;
+  save(join(dir,'attempt.json'),JSON.stringify(state)+'\n');return visible(item);
+}
+async function operate(options,begin,{transport=request,pollIntervalMs=2000}={}) {
+  let lock;
+  try {
+    const loc=locations(options);
+    if(!begin&&!load(loc))fail('approval_setup_required');
+    privateDir(options.directory);privateDir(join(options.directory,'approvals'));privateDir(loc.root);
+    const lockPath=join(loc.root,'.owner.sqlite');
+    try{privateRead(lockPath);}catch(e){if(e.code!=='ENOENT')throw e;}
+    const fd=openSync(lockPath,constants.O_WRONLY|constants.O_CREAT|constants.O_NOFOLLOW,0o600);closeSync(fd);
+    try{lock=new DatabaseSync(lockPath);lock.exec('PRAGMA journal_mode=DELETE; PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner(id INTEGER);');}
+    catch{fail('approval_busy','not_applied',true);}
+    let item=load(loc);
+    if(begin){
+      const replacement=options.replaceRequestId;
+      if(replacement!==undefined&&(!uuid.test(replacement)||!item))fail('selection_conflict');
+      if(replacement!==undefined&&item.state.requestId!==replacement&&item.state.parentRequestId!==replacement)fail('selection_conflict');
+      if(replacement!==undefined&&item.state.requestId===replacement&&item.state.state==='pending')fail('selection_conflict');
+      if(!item||(replacement!==undefined&&item.state.requestId===replacement)){
+        if(readdirSync(loc.root).length>=130)fail('approval_capacity');
+        const label=options.label??options.clientType;
+        if(typeof label!=='string'||label.length>80||/[\u0000-\u001f\u007f]/u.test(label))fail('invalid_request');
+        const state={requestId:randomUUID(),parentRequestId:replacement??null,brokerUrl:loc.broker,clientType:options.clientType,label,token:randomBytes(32).toString('base64url'),state:'pending'};
+        const dir=join(loc.root,state.requestId);privateDir(dir);
+        save(join(dir,'attempt.json'),JSON.stringify(state)+'\n');
+        save(loc.current,JSON.stringify({requestId:state.requestId})+'\n');item={state,dir};
+      }
+    }
+    if(!item)fail('approval_setup_required');
+    if(item.state.state!=='pending')return visible(item);
+    const s=item.state;
+    if(Number.isFinite(s.retryAt)&&s.retryAt>Date.now()&&s.retryAt-Date.now()<=300000)fail(s.retryCode??'rate_limited',s.retryEffect??'unknown',true,s.retryAt-Date.now());
+    if(!begin){
+      const now=Date.now();
+      if(Number.isFinite(s.lastPollAt)&&now>=s.lastPollAt&&now-s.lastPollAt<pollIntervalMs)return visible(item);
+      s.lastPollAt=now;save(join(item.dir,'attempt.json'),JSON.stringify(s)+'\n');
+    }
+    const path=begin?'/v1/enrollment-requests':`/v1/enrollment-requests/${s.requestId}`;
+    const response=await transport(loc.broker,begin?'POST':'GET',path,s.token,begin?{request_id:s.requestId,client_type:s.clientType,label:s.label}:undefined);
+    if(![200,201].includes(response.status)){
+      const code=response.body?.error?.code;
+      let retryAfterMs=response.status===429?60000:5000;
+      if(typeof response.retryAfter==='string'){
+        const seconds=/^[0-9]{1,6}$/.test(response.retryAfter)?Number(response.retryAfter):NaN;
+        const parsed=Number.isFinite(seconds)?seconds*1000:Date.parse(response.retryAfter)-Date.now();
+        if(Number.isFinite(parsed))retryAfterMs=Math.max(1000,Math.min(300000,Math.ceil(parsed)));
+      }
+      if([429,503].includes(response.status)){s.retryAt=Date.now()+retryAfterMs;s.retryCode=code==='not_ready'||code==='storage_unavailable'?code:'rate_limited';s.retryEffect=response.body?.error?.effect==='not_applied'?'not_applied':'unknown';save(join(item.dir,'attempt.json'),JSON.stringify(s)+'\n');}
+      fail(['unauthenticated','forbidden','invalid_request','idempotency_conflict','rate_limited','not_ready','storage_unavailable'].includes(code)?code:'invalid_response',response.body?.error?.effect==='not_applied'?'not_applied':'unknown',[429,503].includes(response.status),retryAfterMs);
+    }
+    delete s.retryAt;delete s.retryCode;delete s.retryEffect;
+    return publish(item,response.body,loc.broker,options.clientType);
+  }catch(e){sanitized(e);}finally{try{lock?.close();}catch{}}
+}
+export const beginApproval=(options,testOptions)=>operate(options,true,testOptions);
+export const pollApproval=(options,testOptions)=>operate(options,false,testOptions);
+
+/** Read only for a helper-enrolled bundle. Missing/corrupt receipt is not a legacy fallback. */
+export function readEnrollmentReceipt({connectionFile,clientType}) {
+  try {
+    if(!TYPES.includes(clientType))fail('invalid_client_type');
+    const bundle=JSON.parse(privateRead(connectionFile));
+    const receipt=JSON.parse(privateRead(join(dirname(connectionFile),'enrollment.json')));
+    const token=privateRead(join(dirname(connectionFile),'token')).trim();
+    if(bundle?.format!=='broker-client-bundle-v1'||bundle.protocol_version!=='1'||bundle.token_file!=='token'||bundle.enrollment_receipt_file!=='enrollment.json'
+      ||bundle.authorization_scheme!=='Bearer'||bundle.authorization_header!=='Authorization'||bundle.insecure_development!==false
+      ||!Array.isArray(bundle.allowed_client_types)||bundle.allowed_client_types.length!==1||bundle.allowed_client_types[0]!==clientType
+      ||receipt?.format!=='psst-enrollment-receipt-v1'||receipt.protocol_version!=='1'||receipt.client_type!==clientType
+      ||receipt.broker_url!==origin(bundle.broker_url)||!/^[A-Za-z0-9_-]{43}$/.test(token)||receipt.token_sha256!==hash(token)
+      ||!/^enrolled-[0-9a-f-]{36}$/.test(receipt.credential_id)||!/^installation-[0-9a-f-]{36}$/.test(receipt.adapter_id)
+      ||!Array.isArray(receipt.scopes)||!receipt.scopes.length||receipt.scopes[0]!==bundle.scope||!Number.isFinite(Date.parse(receipt.expires_at)))fail('invalid_enrollment_receipt');
+    if(Date.parse(receipt.expires_at)<=Date.now())fail('credential_expired');
+    return {credentialId:receipt.credential_id,expiresAt:receipt.expires_at};
+  } catch(e) {
+    if(e.effect&&/^[a-z_]+$/.test(e.code))throw e;
+    fail('invalid_enrollment_receipt');
+  }
+}