@camstack/system 1.0.2

package/dist/builtins/local-auth/oauth-grants.d.ts

@@ -0,0 +1,45 @@
+import { ISsoBridgeProvider, TokenScope } from '@camstack/types';
+import { OauthSessionManager } from './oauth-session-manager.js';
+interface IssueCodeInput {
+    integrationId: string;
+    userId: string;
+    username: string;
+    scopes: TokenScope[];
+    redirectUri: string;
+    hubUrl: string;
+}
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+interface VerifiedAccess {
+    userId: string;
+    username: string;
+    scopes: TokenScope[];
+}
+/** OAuth account-linking grant logic. Pure over an injected sso-bridge
+ *  signer so it is unit-testable without the capability registry.
+ *
+ *  Authorization codes are short-lived (60 s). The `redirectUri`,
+ *  `integrationId`, and a unique `jti` are embedded in the signed JWT
+ *  so the HMAC signature is the real security boundary. Single-use is
+ *  enforced by a `jti` consumed-set. The old in-process `pendingCodes`
+ *  Map is gone — a hub restart no longer breaks in-flight exchanges,
+ *  only risking a single replay within the remaining 60 s TTL. */
+export declare function createOauthGrants(ssoBridge: ISsoBridgeProvider, sessionManager: OauthSessionManager): {
+    oauthIssueCode(input: IssueCodeInput): Promise<{
+        code: string;
+    }>;
+    oauthExchangeCode(input: {
+        code: string;
+        redirectUri: string;
+    }): Promise<TokenPair | null>;
+    oauthRefresh(input: {
+        refreshToken: string;
+    }): Promise<TokenPair | null>;
+    oauthVerifyAccessToken(input: {
+        token: string;
+    }): Promise<VerifiedAccess | null>;
+};
+export {};

package/dist/builtins/local-auth/oauth-session-manager.d.ts

@@ -0,0 +1,50 @@
+import { TokenScope, SettingsStoreClient } from '@camstack/types';
+export interface OauthSession {
+    readonly id: string;
+    readonly userId: string;
+    readonly username: string;
+    readonly integrationId: string;
+    readonly scopes: TokenScope[];
+    readonly createdAt: number;
+    readonly lastUsedAt: number;
+    readonly revokedAt: number | null;
+}
+interface CreateInput {
+    readonly userId: string;
+    readonly username: string;
+    readonly integrationId: string;
+    readonly scopes: TokenScope[];
+}
+export declare class OauthSessionManager {
+    private readonly store;
+    constructor(store: SettingsStoreClient);
+    /**
+     * Create a new OAuth session record. Generates a UUID as the session id,
+     * sets `createdAt` and `lastUsedAt` to now, `revokedAt` to null.
+     */
+    create(input: CreateInput): Promise<OauthSession>;
+    /**
+     * Return all sessions — both active and revoked. Callers decide
+     * whether to filter by `revokedAt`.
+     */
+    list(): Promise<OauthSession[]>;
+    /**
+     * Look up a session by its id. Returns null when not found.
+     */
+    getById(id: string): Promise<OauthSession | null>;
+    /**
+     * Mark a session as revoked by setting `revokedAt = now`.
+     *
+     * - Returns `true` on success (including idempotent re-revoke — the
+     *   existing `revokedAt` timestamp is preserved; it is NOT updated).
+     * - Returns `false` when the session id is not found.
+     */
+    markRevoked(id: string): Promise<boolean>;
+    /**
+     * Update `lastUsedAt` to now. No-op (does not throw) when the session
+     * id is not found — the caller (token-use hot path) should not fail
+     * for a missing session that may have been concurrently revoked.
+     */
+    touch(id: string): Promise<void>;
+}
+export {};

package/dist/builtins/local-network/index.d.ts

@@ -0,0 +1,2 @@
+export { LocalNetworkAddon, classifyKind, prefixLen } from './local-network.addon.js';
+export { LocalNetworkAddon as default } from './local-network.addon.js';

package/dist/builtins/local-network/index.js

@@ -0,0 +1,10 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Cek0wNdY.js");
+const require_builtins_local_network_local_network_addon = require("./local-network.addon.js");
+exports.LocalNetworkAddon = require_builtins_local_network_local_network_addon.LocalNetworkAddon;
+exports.classifyKind = require_builtins_local_network_local_network_addon.classifyKind;
+exports.default = require_builtins_local_network_local_network_addon.LocalNetworkAddon;
+exports.prefixLen = require_builtins_local_network_local_network_addon.prefixLen;

package/dist/builtins/local-network/index.mjs

@@ -0,0 +1,2 @@
+import { LocalNetworkAddon, classifyKind, prefixLen } from "./local-network.addon.mjs";
+export { LocalNetworkAddon, LocalNetworkAddon as default, classifyKind, prefixLen };

package/dist/builtins/local-network/local-network.addon.d.ts

@@ -0,0 +1,150 @@
+import { ProviderRegistration, LocalInterface, ConnectionEndpoint, BaseAddon } from '@camstack/types';
+/**
+ * Cached mesh-reachable endpoint, learned from the `mesh-network`
+ * provider via the `MeshNetworkChanged` event-tail + pull-reconcile.
+ * `null` when no mesh provider is joined / reachable.
+ */
+interface MeshEndpointCache {
+    /** Preferred mesh host — MagicDNS name when available, else raw mesh IP. */
+    readonly host: string;
+    /** Hub HTTPS port the mesh endpoint targets. */
+    readonly port: number;
+}
+interface LocalNetworkConfig {
+    /** Empty = "auto" (every non-loopback / non-link-local address
+     *  participates). Non-empty restricts the candidate set to only
+     *  those operator-pinned addresses. */
+    readonly allowedAddresses: readonly string[];
+    /** Sentinel — `true` after the first-boot auto-seed runs. Lets the
+     *  addon distinguish "fresh install, never touched" (false → seed
+     *  with LAN/Wi-Fi addresses) from "operator explicitly cleared the
+     *  allowlist" (true + empty → respect operator's choice). */
+    readonly bootSeeded: boolean;
+}
+export declare class LocalNetworkAddon extends BaseAddon<LocalNetworkConfig> {
+    private pollTimer;
+    private lastSnapshotKey;
+    /** Optional public hostname tracked from `NetworkTunnelStarted`/
+     *  `Stopped` events on the bus. */
+    private publicHostname;
+    /**
+     * Mesh-reachable endpoint (Tailscale MagicDNS / 100.x), learned from
+     * the `MeshNetworkChanged` event-tail and refreshed by a pull-reconcile
+     * before each `getConnectionEndpoints` build (events are lossy — D8).
+     * `null` when no mesh provider is joined.
+     */
+    private meshEndpoint;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    /**
+     * Other hub addons (e.g. cloudflare-tunnel) signal the active public
+     * FQDN by emitting `NetworkTunnelStarted` on the bus — handled in
+     * `onInitialize`. This setter exists for tests + future direct
+     * callers; cleared by passing an empty string.
+     */
+    setPublicHostname(hostname: string): void;
+    /**
+     * Replace the cached mesh endpoint. Set from the `MeshNetworkChanged`
+     * event-tail + the pull-reconcile; exposed for tests + future direct
+     * callers. Pass `null` to clear (mesh left / no provider joined).
+     */
+    setMeshEndpoint(endpoint: MeshEndpointCache | null): void;
+    /**
+     * Refresh the cached mesh endpoint from the authoritative forked
+     * `mesh-network` provider(s). `mesh-network` is a COLLECTION cap on a
+     * forked addon, so the hub builtin can't see it via `ctx.api` /
+     * `getCollectionEntries` — we resolve each provider by addonId through
+     * the hub-side `capabilityRegistry.getProviderByAddon` resolver (the
+     * same mechanism `device-manager` uses for cross-process exporter
+     * contributions). Best-effort: a provider that's absent / errors /
+     * not joined simply contributes nothing.
+     */
+    private reconcileMeshEndpoint;
+    private enumerate;
+    private detectChanges;
+}
+/**
+ * Lift `os.networkInterfaces()` into our `LocalInterface[]` shape with
+ * kind classification + preferred flag. Pure — takes the raw result so
+ * tests can feed synthetic data.
+ */
+interface OsNetworkInterfaceInfo {
+    readonly family: string;
+    readonly address: string;
+    readonly cidr?: string | null;
+    readonly netmask: string;
+    readonly internal: boolean;
+    readonly mac: string;
+}
+export declare function enumerateOsInterfaces(ifaces: NodeJS.Dict<readonly OsNetworkInterfaceInfo[]>): readonly LocalInterface[];
+/**
+ * Filter the interface list by the operator's allowlist. Empty
+ * allowlist = no-op (every interface passes); otherwise only entries
+ * whose `address` matches an allowlist entry remain. Loopback always
+ * survives so the SDK keeps `127.0.0.1` as the last-resort fallback.
+ */
+export declare function applyAllowlist(interfaces: readonly LocalInterface[], allowed: readonly string[]): readonly LocalInterface[];
+/**
+ * Rank interfaces and pick the auto-selected outbound one. See the
+ * cap's `getPreferred` doc for the heuristic.
+ */
+export declare function pickPreferred(interfaces: readonly LocalInterface[]): LocalInterface | null;
+/**
+ * Build the ordered candidate URL list. Priority schema:
+ *   0       — preferred LAN IPv4
+ *   10+     — other LAN IPv4
+ *   100     — public tunnel hostname (always HTTPS)
+ *   150     — mesh endpoint (Tailscale MagicDNS / 100.x, always HTTPS)
+ *   200+    — LAN IPv6
+ *   1000    — loopback (last resort)
+ *
+ * The mesh endpoint ranks just below a true public funnel (a Funnel is
+ * reachable by ANY client; the mesh needs the peer on the same tailnet)
+ * but above the IPv6 / loopback fallbacks — giving remote, mesh-joined
+ * clients a working candidate when no public tunnel is up.
+ *
+ * `scheme` controls LAN + loopback URLs. Browsers running over HTTPS
+ * block `http://` candidates as mixed content, so callers loaded over
+ * HTTPS should pass `scheme: 'https'` even when probing a LAN IP — the
+ * hub's cert manager already issues a SAN-multi cert covering local
+ * interfaces. The public tunnel + mesh endpoint always emit `https://`
+ * (the tunnel edge / the hub itself terminates TLS).
+ */
+export declare function buildEndpoints(interfaces: readonly LocalInterface[], port: number, includeLoopback: boolean, ipv4Only: boolean, publicHostname: string, scheme?: 'http' | 'https', meshEndpoint?: MeshEndpointCache | null): ConnectionEndpoint[];
+/**
+ * First-boot heuristic: which addresses should the allowlist start
+ * with? Includes LAN + Wi-Fi IPv4 addresses + plausible IPv6:
+ *
+ *   - **IPv4**: skip link-local (`169.254.*`), keep the rest.
+ *   - **IPv6**: skip link-local (`fe80::*`), unspecified, and
+ *     multicast. Keep ULAs (`fc00::/7` → `fc??:` / `fd??:`) and Global
+ *     Unicast addresses (`2000::/3` → `2???`/`3???`). Privacy-extension
+ *     temporary addresses get included by default; the operator can
+ *     prune them from the Network Addresses tab if the rotating IPs
+ *     become a nuisance.
+ *
+ * Skips docker/vpn/loopback/other entirely — those stay opt-in.
+ */
+export declare function autoSeedAllowlist(interfaces: readonly LocalInterface[]): string[];
+/**
+ * Per-interface tooltip text surfaced on the "Unlikely usable" badge.
+ * Server-side so the UI doesn't re-derive the rationale (single source
+ * of truth). Returns `''` for plausible entries; the addon overlays
+ * this on the `LocalInterface.plausibleReason` field.
+ */
+export declare function explainNonPlausible(input: {
+    readonly kind: LocalInterface['kind'];
+    readonly family: 'IPv4' | 'IPv6';
+    readonly address: string;
+    readonly internal: boolean;
+}): string;
+/**
+ * Per-address gate used by `autoSeedAllowlist`. Exposed for tests so
+ * we can pin every classification rule without standing up the addon.
+ */
+export declare function isPlausibleAutoSeed(address: string, family: 'IPv4' | 'IPv6'): boolean;
+export declare function classifyKind(name: string, address: string, internal: boolean): LocalInterface['kind'];
+/** Convert an IPv4/IPv6 netmask string to its prefix length (CIDR). */
+export declare function prefixLen(netmask: string): number;
+export {};