@hypit/hypit 0.2.0 → 0.2.1

package/README.md

@@ -110,7 +110,7 @@ Drop in a video and your agent clones the whole workflow — or describe what yo
 
 ## Stay Tuned with Us
 
-Star Hypit to bookmark the project. To receive release notifications, select **Watch → Custom → Releases** on GitHub.
+Star us, and you will receive all release notifications from GitHub without any delay!
 
 ![Stay tuned with us](https://storage.googleapis.com/hypit-public-assets/showcase/npm/2026-09-10/star.gif)
 

package/examples/provider-package/hypit.runtime.json

@@ -1,11 +1,11 @@
 {
   "format": "hypit.runtime-local@1",
   "dataRoot": ".hypit/execution",
-  "credentials": { "os": { "use": "@hypit/credential-store-os" } },
+  "credentials": { "platform": { "use": "@hypit/credential-store-platform" } },
   "endpoints": {
     "images.personal": {
       "use": "@example/provider-images",
-      "config": { "baseUrl": "https://images.example", "apiKey": { "store": "os", "key": "images.personal" } }
+      "config": { "baseUrl": "https://images.example", "apiKey": { "store": "platform", "key": "images.personal" } }
     }
   },
   "bindings": { "@hypit/gpt-image@1#gpt-image-2": "images.personal" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -205,6 +205,7 @@
     "@hypit/credential-store-env": "workspace:*",
     "@hypit/credential-store-file": "workspace:*",
     "@hypit/credential-store-os": "workspace:*",
+    "@hypit/credential-store-platform": "workspace:*",
     "@hypit/deck-track": "workspace:*",
     "@hypit/deck-track-studio": "workspace:*",
     "@hypit/elevenlabs-speech": "workspace:*",

package/packages/credential-store-file/README.md

@@ -4,7 +4,9 @@ A writable CredentialStore for a deployment that explicitly chooses local file s
 Linux without an OS credential locker. It stores unencrypted credential values in an owner-private
 directory outside the video project. On Windows the selected directory must have a private user ACL;
 POSIX file modes do not set Windows ACLs. Choose `@hypit/credential-store-os` when using macOS Keychain
-or Windows Credential Locker, or `@hypit/credential-store-env` for externally supplied, read-only values.
+or Windows Credential Locker, `@hypit/credential-store-platform` for OS storage on macOS/Windows
+and this file Store on Linux or `@hypit/credential-store-env` for externally
+supplied, read-only values.
 
 ## Select it before login
 

package/packages/credential-store-os/README.md

@@ -11,3 +11,7 @@ bytes do not appear in command arguments or temporary files.
 
 Use `hypit auth login <endpoint> --runtime <profile>` to write the selected credential and
 `hypit auth logout` to remove it.
+
+A Profile that must also run on Linux can select `@hypit/credential-store-platform`:
+that package uses this Store on macOS and Windows, and an unencrypted, owner-private file on Linux.
+Selecting `@hypit/credential-store-os` directly continues to require macOS or Windows.

package/packages/credential-store-platform/README.md

@@ -0,0 +1,62 @@
+# `@hypit/credential-store-platform`
+
+An explicitly selected CredentialStore policy: macOS Keychain on macOS, Windows Credential Locker
+on Windows, and an unencrypted, owner-private file on Linux. Other platforms are unsupported by this
+package and report an error. Linux may offer other credential services; this package chooses file
+storage there and does not detect or integrate those services.
+
+A Profile can select this package to use that policy on Linux, macOS and Windows.
+`@hypit/credential-store-os`, `@hypit/credential-store-file` and `@hypit/credential-store-env`
+remain selectable directly for a deployment with a different storage choice.
+
+## Select it
+
+```json
+{
+  "credentials": {
+    "platform": { "use": "@hypit/credential-store-platform" }
+  },
+  "endpoints": {
+    "hypihub.default": {
+      "use": "@hypit/provider-hypihub",
+      "config": {
+        "baseUrl": "https://hypit.ai",
+        "apiKey": { "store": "platform", "key": "hypihub.oauth" }
+      }
+    }
+  }
+}
+```
+
+The Endpoint still owns its acquisition flow and the Store only persists the result:
+
+```bash
+hypit auth login hypihub.default --runtime <profile>
+hypit auth status hypihub.default --runtime <profile>
+hypit auth logout hypihub.default --runtime <profile>
+```
+
+## What it does not do
+
+The choice is made once per host, from the platform the Runtime is running on. This is not a lookup
+chain: a miss or failure in one store never tries another, and no credential is migrated between them. A
+credential stored in a locker stays in that locker; a credential stored in a file stays in that file.
+
+## Configuration
+
+- `path` selects the directory for Linux file storage, resolved against the Host state root printed by
+  `hypit paths`. The default is the same `credentials` directory `@hypit/credential-store-file` uses,
+  so on Linux, switching between the two Stores finds the credential already stored.
+- `service` selects the locker service name. The OS Store's own default applies when it is absent.
+
+## Storage on each platform
+
+On macOS and Windows the credential is held by the platform locker, with exactly the rules of
+`@hypit/credential-store-os`: it is encrypted and access-controlled by the operating system, and it
+is not readable from another machine.
+
+On Linux the credential is held by an owner-private document with exactly the rules of
+`@hypit/credential-store-file`: unencrypted JSON, one document per key, directory mode `0700`, file
+mode `0600`, outside the video project, and never enumerated or indexed. Filesystem path-length
+limits apply to an overlong key, which fails rather than selecting another name. A damaged document
+can be replaced by `auth login` or deleted by `auth logout` without decoding the old value.

package/packages/credential-store-platform/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypit/credential-store-platform",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/credential-store-file": "workspace:*",
+    "@hypit/credential-store-os": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  }
+}

package/packages/credential-store-platform/src/activation.ts

@@ -0,0 +1,39 @@
+import { join, resolve } from "node:path";
+import {
+  createRuntimeCredentialStoreAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+import { PlatformCredentialStore } from "./store.js";
+
+const platformCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
+  use: "@hypit/credential-store-platform",
+  validate(context) {
+    const config = runtimeConfigObject(context.config, "platform CredentialStore");
+    runtimeConfigExact(config, ["path", "service"], "platform CredentialStore");
+    runtimeConfigString(config.path, "platform credential path");
+    runtimeConfigString(config.service, "platform credential service");
+  },
+  open(context) {
+    const config = runtimeConfigObject(context.config, "platform CredentialStore");
+    const path = runtimeConfigString(config.path, "platform credential path");
+    const service = runtimeConfigString(config.service, "platform credential service");
+    return {
+      value: new PlatformCredentialStore({
+        // Linux uses the same directory the file Store uses by default, so a Profile
+        // that switches between them on Linux finds the credential it stored.
+        directory: path === undefined
+          ? join(context.hostStateRoot, "credentials")
+          : resolve(context.hostStateRoot, path),
+        ...(service === undefined ? {} : { service }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [platformCredentialStoreAdapter],
+};
+export default hypitPackage;

package/packages/credential-store-platform/src/index.ts

@@ -0,0 +1 @@
+export { PlatformCredentialStore } from "./store.js";

package/packages/credential-store-platform/src/store.ts

@@ -0,0 +1,89 @@
+import {
+  credentialRef,
+  verifyCredentialRef,
+} from "@hypit/runtime";
+import type {
+  CredentialRef,
+  CredentialValue,
+  WritableCredentialStore,
+} from "@hypit/runtime";
+import { FileCredentialStore } from "@hypit/credential-store-file";
+import { OsCredentialStore } from "@hypit/credential-store-os";
+import type {
+  OsCredentialDeleter,
+  OsCredentialReader,
+  OsCredentialWriter,
+} from "@hypit/credential-store-os";
+
+export type PlatformCredentialStoreOptions = {
+  /** Directory holding the documents this Store selects on Linux. */
+  readonly directory: string;
+  /** Service the locker's entries are filed under; the OS Store's own default applies where absent. */
+  readonly service?: string;
+  /**
+   * The platform to select for, defaulting to the running one. A Profile never states this: it is
+   * separate so the selection can be exercised on one machine for every platform.
+   */
+  readonly platform?: NodeJS.Platform;
+  /** Locker backend to read and write with, where the platform's own locker is not the one to use. */
+  readonly locker?: {
+    readonly read: OsCredentialReader;
+    readonly write: OsCredentialWriter;
+    readonly remove: OsCredentialDeleter;
+  };
+};
+
+/**
+ * An explicitly selected storage policy: OS credentials on macOS/Windows, files on Linux.
+ * The selected backend's errors propagate; other platforms are unsupported by this package.
+ */
+export class PlatformCredentialStore implements WritableCredentialStore {
+  readonly #delegate: WritableCredentialStore;
+  readonly #backing: "os" | "file";
+
+  constructor(options: PlatformCredentialStoreOptions) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin" || platform === "win32") {
+      this.#backing = "os";
+      this.#delegate = new OsCredentialStore({
+        ...(options.service === undefined ? {} : { service: options.service }),
+        ...options.locker,
+      });
+    } else if (platform === "linux") {
+      this.#backing = "file";
+      this.#delegate = new FileCredentialStore(options.directory);
+    } else {
+      throw new Error(`Platform CredentialStore does not support ${platform}; select an explicit CredentialStore supported by this host`);
+    }
+  }
+
+  owns(ref: CredentialRef): boolean {
+    return ref.store === "platform";
+  }
+
+  /**
+   * Each delegate owns its own name and refuses refs filed under another, so a ref this Store owns
+   * is retargeted before the delegate sees it. Only the name changes; the opaque key is untouched.
+   */
+  #translated(ref: CredentialRef): CredentialRef {
+    return credentialRef(this.#backing, ref.key);
+  }
+
+  async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) return undefined;
+    return await this.#delegate.resolve(this.#translated(ref));
+  }
+
+  async put(ref: CredentialRef, value: CredentialValue): Promise<void> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`Platform CredentialStore does not own ${ref.store}`);
+    await this.#delegate.put(this.#translated(ref), value);
+  }
+
+  async delete(ref: CredentialRef): Promise<boolean> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`Platform CredentialStore does not own ${ref.store}`);
+    return await this.#delegate.delete(this.#translated(ref));
+  }
+}