Companion App — Phase 7 production distribution

Status: source implementation prepared; no release has been signed, notarized, installed, or published. This document does not qualify W4 and does not change the sealed W4/C17 record.

Release contract

The first production candidate is Knowtation 0.1.0 (build 100) for macOS 14 or later on Apple silicon (arm64). It is a direct-download Developer ID distribution.

The release produces a notarized app ZIP, a notarized installer package, a signed update manifest, checksums, the Knowtation license, an SPDX SBOM, third-party notices, and sanitized release evidence. Exact names and public metadata are in release/macos/release.json.

What is bundled

The app contains the native launchers, custody helper, Node 24.21.0, the exact npm production closure from companion/runtime/package-lock.json, the existing Knowtation CLI and MCP source, the local inference worker, and the pinned Xenova/all-MiniLM-L6-v2 ONNX model. Node, npm, model files, critical inference runtime files, source inclusion, architecture, and excluded packages are fixed by:

• release/macos/release-lock.json
• release/macos/runtime-files.json
• companion/runtime/package-lock.json

acquire-inputs.sh verifies downloaded sizes and SHA-256 hashes. build.sh rebuilds native npm modules for arm64, removes foreign prebuilds and package-manager tooling, checks critical W3 hashes, generates license closure and the SPDX SBOM, and seals every resource by path, size, mode, and hash. Symbolic links and unexpected files fail verification. The final manifest records exact committed Muse and Git revisions; final release generation rejects an uncommitted source identity.

Core app, CLI, MCP, custody, OAuth, storage, and inference paths use only the bundle and macOS system frameworks. Two existing integrations remain explicitly optional: vault sync uses a separately installed git, and MCP prime context uses a separately installed muse. Their absence produces the fixed failure behavior recorded in release.json; neither is part of the signed dependency closure.

Authentication and custody

The app uses the existing native OAuth Authorization Code + PKCE loopback flow against the fixed issuer https://mcp.knowtation.store/api/v1/auth/native. Discovery and every endpoint must exactly match that HTTPS issuer. The app dynamically registers a public client, opens the system browser, validates state and issuer, and stores access/refresh tokens through the custody helper.

The custody helper validates the real XPC sender audit token and accepts only same-team signed app, CLI, and MCP identifiers. It stores secrets in the macOS Data Protection Keychain under the custody helper's restricted keychain access group. The app, CLI, MCP process, model worker, logs, and release evidence never receive the Keychain entitlement or print token values. A one-use inherited socket capability gives each accepted signed caller only its allowed custody operations.

Native refresh records now retain client_id and scopes in durable server state. Refresh therefore survives a gateway restart while remaining bound to the original public client. The release source includes this gateway change; production deployment of that source is a separate approval and must occur before release acceptance.

The signed CLI and MCP executable load a valid stored session and inject it only into their bundled child runtime. Caller-provided KNOWTATION_HUB_URL and KNOWTATION_HUB_TOKEN variables are removed by the signed launcher. companion verify-session returns only an authenticated boolean and scope names, providing caller evidence without exposing identity or credentials.

Signing and notarization

Every Mach-O code object is signed from the inside out with hardened runtime and a secure timestamp. The custody helper also embeds and validates a Developer ID provisioning profile containing the restricted application identifier and keychain access group. Debugging and disabled library validation entitlements are forbidden. The outer app and installer are submitted separately to Apple notarization and each notarization ticket is stapled and validated.

Private signing material is external input. No certificate, .p12, API key, provisioning secret, notary credential, or update private key belongs in the repository or release bundle.

Update and rollback policy

Release metadata is signed with a separate offline Ed25519 key. The app carries only its public key and key ID. Verification binds the signature, public trust record, exact package hash and size, platform, architecture, source-build range, target build, expiry, complete artifact hashes, and committed source revisions.

Build numbers are strictly increasing. The installer refuses build 100 when an installed app has a higher build. An operational rollback must rebuild the previous known-good source as a new higher build, then sign, notarize, and publish a new manifest. Reusing or republishing an old lower build is forbidden. Build 100 establishes the update trust root; a second signed release is still required to produce real update-chain and rollback-rejection evidence for W4.

The implementation provides a signed manual update package and verifier. It does not silently fetch or install updates in the background. Publication and installation remain explicit release-operator actions.

Required acceptance tests

Before publication, the release operator must capture all of the following against the exact final artifacts:

1. Swift custody, signature, runtime-manifest, and update-policy tests.
2. Focused JavaScript packaging, OAuth durability, lifecycle, closure, tamper, and rollback tests.
3. The full tracked repository suite and a zero-vulnerability audit of the bundled runtime lock.
4. Clean Gatekeeper, code-signature, package-signature, notarization-ticket, checksum, ZIP, SBOM, license, architecture, and secret-file verification.
5. Installed signed app lifecycle: start, helper registration, parent-bound runtime stop, restart.
6. Signed app, CLI, and MCP custody access; unsigned-caller denial; hosted session verification from both CLI and MCP; MCP initialization; modified-resource rejection.
7. On a later higher build, accepted forward update plus rejection of substituted, expired, wrong-key, wrong-source-range, and lower-build manifests/packages.

The exact operator sequence is in docs/runbooks/KNOWTATION-MACOS-RELEASE.md.