loki-mode 7.79.0 → 7.80.1

package/docs/ENTERPRISE-IDENTITY-ROADMAP.md

@@ -0,0 +1,206 @@
+# Enterprise Identity Roadmap
+
+This document scopes Loki Mode's enterprise identity surface honestly. It
+separates what is shipped today from what is roadmap. Nothing in the
+"Roadmap" section ships today. Where a capability is not built, it is labeled
+as such, with a real effort estimate and the identity-provider (IdP) or test
+infrastructure it would require.
+
+The intent is to give a precise, non-aspirational picture so that marketing,
+sales, and docs never overstate the enterprise identity story.
+
+## 1. Current state (shipped, verified)
+
+Everything in this section is backed by code in `dashboard/auth.py` and
+`dashboard/server.py`. Function names are cited so claims can be checked.
+
+### Token authentication
+
+- Opt-in via `LOKI_ENTERPRISE_AUTH=true` (off by default).
+  See `ENTERPRISE_AUTH_ENABLED` and `is_enterprise_mode()` in
+  `dashboard/auth.py`.
+- API tokens are minted, hashed (per-token random salt, SHA-256), revoked,
+  deleted, and listed:
+  `generate_token()`, `revoke_token()`, `delete_token()`, `list_tokens()`,
+  `validate_token()`. Tokens are stored at `~/.loki/dashboard/tokens.json`
+  with enforced `0600` permissions (`_save_tokens()`).
+- Token validation iterates all entries with a constant-time compare to avoid
+  leaking token count via timing (`validate_token()` plus
+  `_constant_time_compare()`).
+
+### OIDC bearer-token validation (the closest foundation for SSO)
+
+- Opt-in via `LOKI_OIDC_ISSUER` + `LOKI_OIDC_CLIENT_ID`.
+  See `OIDC_ENABLED` and `is_oidc_mode()` in `dashboard/auth.py`.
+- Inbound JWTs are validated by `validate_oidc_token()`. When PyJWT +
+  cryptography are installed, signatures are cryptographically verified
+  (RS256/RS384/RS512) against the provider's JWKS endpoint, with issuer and
+  audience checks (`_get_oidc_config()`, `_get_jwks()`).
+- Without PyJWT, tokens are rejected unless `LOKI_OIDC_SKIP_SIGNATURE_VERIFY`
+  is explicitly set (insecure, local-testing only, loudly logged as critical).
+- Role/group claims are mapped to Loki roles by `_scopes_from_claims()` /
+  `_collect_role_claims()`, supporting generic `roles`/`groups`, Keycloak
+  `realm_access.roles`, AWS Cognito `cognito:groups`, and a configurable
+  claim (`LOKI_OIDC_ROLES_CLAIM`). Unrecognized claims fall back to the
+  least-privileged default role (`_default_oidc_role()`, default `viewer`),
+  never admin.
+
+  IMPORTANT distinction: this is server-side validation of a bearer JWT that
+  some other system obtained. Loki does NOT implement a browser login flow,
+  an authorization-code exchange, or an end-user SSO redirect. A separate
+  component must perform the user-facing sign-in and present the resulting
+  JWT to Loki.
+
+### Scopes and predefined roles (read/control style authorization)
+
+- Four predefined roles in `ROLES`: `admin`, `operator`, `viewer`,
+  `auditor`. Scope hierarchy (`_SCOPE_HIERARCHY`, `has_scope()`):
+  `*` -> `control` -> `write` -> `read`, plus `audit`/`admin`.
+- Endpoint enforcement via the `require_scope()` dependency factory and the
+  `get_current_token()` FastAPI dependency. When neither auth mode is enabled,
+  access is anonymous (local-first default).
+
+### Dashboard transport gating (added in Release A)
+
+- WebSocket auth gating: the dashboard validates a bearer token (header or
+  `?token=`/`?access_token=` query for browser clients) at the mount
+  boundary before delegating, mirroring the HTTP `get_current_token` order
+  (OIDC first, then loki token). See `_MountAuthGuard._validate_ws_token()`
+  and `_ws_token_from_scope()` in `dashboard/server.py`.
+- REST scope consistency: `/api/memory` and `/api/collab` endpoints were
+  brought in line with the read/control scope model so they are not reachable
+  unauthenticated when enterprise auth is on.
+- Webhook/trigger HMAC: the external trigger surface requires a shared secret
+  and rejects unsigned/mismatched requests (constant-time compare via
+  `hmac.compare_digest`, surfaced through `_constant_time_compare()`).
+
+### Tenant isolation (data-plane, present but minimal)
+
+- A `Tenant` model exists (`dashboard/models.py`: `class Tenant`, with
+  `Project.tenant_id` foreign keys) and the v2 API enforces a tenant boundary
+  derived from a trusted, server-validated `tenant:<id>` scope on the token
+  (`dashboard/api_v2.py`: `TENANT_SCOPE_PREFIX`). A non-admin token is pinned
+  to one tenant; cross-tenant requests are denied with 403; an un-scoped
+  token reaches no tenant-scoped resource.
+- This is project-level data isolation keyed off a token scope. It is NOT a
+  full tenant RBAC system (no roles per tenant, no per-tenant policy
+  administration, no tenant lifecycle management UI). See the roadmap below.
+
+### What the infrastructure OIDC is (and is NOT)
+
+The OIDC referenced in the Terraform and Helm assets is workload identity
+(IRSA on AWS / Workload Identity on GCP) used so the running pods can assume
+cloud roles. That is machine-to-cloud authentication, not end-user SSO.
+
+Likewise, Kubernetes RBAC and NetworkPolicy in the Helm chart govern what the
+cluster service accounts and pods may do. They are cluster-plane controls and
+are unrelated to product-level or per-tenant authorization for Loki users.
+Do not conflate cluster RBAC with application RBAC.
+
+## 2. Roadmap (NOT built)
+
+None of the items below are implemented. Each lists honest scope, a rough
+effort estimate, and the IdP or test infrastructure required.
+
+### SSO / SAML (browser sign-in flow)
+
+- Scope: a user-facing single sign-on flow. Two sub-paths:
+  - OIDC authorization-code login (closer to today's code): a browser
+    redirect to the IdP, code exchange, session/cookie issuance, and CSRF/
+    state handling. The existing `validate_oidc_token()` already validates the
+    resulting JWT, so this is the smaller of the two.
+  - SAML 2.0 (still common in large enterprises): SP metadata, ACS endpoint,
+    XML signature validation, NameID/attribute mapping, and IdP-initiated and
+    SP-initiated flows.
+- Effort: OIDC login flow on top of the existing validator is roughly a few
+  weeks (1 engineer) including session management and tests. Full SAML 2.0 is
+  larger, on the order of 1 to 2 months, because XML signature handling and
+  multi-IdP quirks are involved; using a vetted SAML library is mandatory
+  rather than hand-rolling.
+- Needs: a real IdP to test against (Okta, Azure AD/Entra ID, or Auth0; a
+  free developer tenant works for early dev). Integration tests must run
+  against that IdP, not mocks alone.
+
+### SCIM user/group provisioning
+
+- Scope: a SCIM 2.0 server so an IdP can create/update/deactivate users and
+  push group membership automatically, instead of users being created on
+  first login. Requires `/scim/v2/Users` and `/scim/v2/Groups` endpoints,
+  filtering, pagination, PATCH semantics, and mapping SCIM groups onto Loki
+  roles/tenants.
+- Effort: roughly 1 to 1.5 months (1 engineer) for a conformant subset plus a
+  persistence model for provisioned identities (today there is no durable
+  user store; OIDC users are derived per-request from claims).
+- Needs: a SCIM-capable IdP to drive the provisioning (Okta or Azure AD), plus
+  a SCIM conformance test harness. This depends on a real user-store model
+  landing first.
+
+### App-level / tenant RBAC
+
+- Scope: roles and policy that go beyond the current four global roles and
+  the `read`/`control` scope hierarchy. Concretely: roles scoped per tenant,
+  per-tenant policy administration, custom roles, resource-level permissions,
+  and an admin surface to manage them.
+- Current state to build on: `Tenant`/`Project` models exist and a
+  `tenant:<id>` scope pins a token to one tenant (data isolation). What is
+  missing: per-tenant role assignment, a policy model richer than the global
+  scope hierarchy, custom/role-definition management, and any UI for it.
+- Effort: roughly 1 to 2 months (1 to 2 engineers) depending on how much
+  policy flexibility is committed to (a fixed per-tenant role set is the
+  smaller end; arbitrary custom roles and resource-level rules is the larger
+  end).
+- Needs: no external IdP, but it pairs naturally with SCIM (group-to-role
+  mapping) and benefits from the durable user store noted above.
+
+### SOC2
+
+- Scope: SOC2 is a compliance PROGRAM, not a code feature. It spans durable,
+  tamper-evident audit logging with retention and SIEM export, access reviews,
+  change-management process, vendor management, security policies, and a Type
+  II observation window (commonly 6 to 12 months of evidence collected under
+  an auditor).
+- What exists today that helps but does not constitute SOC2: hash-chained
+  audit logging and syslog/SIEM forwarding (see the audit-logging docs). These
+  are inputs to an audit, not the certification.
+- Effort: multi-quarter organizational work, typically 6 to 12 months elapsed,
+  involving engineering, security, and an external auditor. It is not a sprint
+  and should never be represented as a shippable feature.
+- Needs: an auditor engagement, an evidence/observation window, and
+  organizational process, in parallel with (not blocking) the code items above.
+
+## 3. Sequencing recommendation
+
+1. OIDC authorization-code login flow first. It reuses the existing
+   `validate_oidc_token()` validator, is the smallest increment, and unlocks
+   the most common "we need SSO" enterprise requirement with the least new
+   surface. This is the natural next code step after today's OIDC bearer
+   validation.
+2. App-level / tenant RBAC next, building on the existing `Tenant` model and
+   `tenant:<id>` scope. Most mid-market and enterprise deals ask for "roles
+   and tenant isolation" once SSO is in place.
+3. SCIM after a durable user store exists (it depends on one). SCIM is a
+   larger-enterprise ask and is most valuable once SSO and RBAC are stable.
+4. SAML in parallel with or after the OIDC login flow, only when a target
+   account specifically requires SAML rather than OIDC. Many enterprises
+   accept OIDC, so do not build SAML speculatively.
+5. SOC2 runs as parallel organizational work, started early because of the
+   observation window, but tracked separately from the code roadmap. The
+   existing audit-log foundation is a head start, not a finish line.
+
+Rationale: OIDC login -> tenant RBAC -> SCIM is the path that unlocks the most
+enterprise deals soonest while reusing the most existing code. SAML is
+demand-gated. SOC2 is long-lead org work that should begin in parallel rather
+than block feature delivery.
+
+## 4. What we do NOT claim
+
+Loki Mode does NOT today ship: a browser SSO login flow, SAML support, SCIM
+provisioning, app-level or per-tenant RBAC beyond the global four-role / read-
+control scope model and the `tenant:<id>` data-isolation scope, or SOC2
+certification. The shipped identity surface is: opt-in token auth, opt-in OIDC
+bearer-token validation, a read/control scope model with four predefined
+roles, dashboard WebSocket and REST auth gating, webhook HMAC verification,
+and tenant data isolation via a token scope. Workload-identity OIDC (IRSA /
+Workload Identity) and Kubernetes RBAC/NetworkPolicy are infrastructure
+controls and are not end-user SSO or product RBAC. Any statement beyond this
+is roadmap, not a current capability.

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.79.0
+**Version:** v7.80.1
 
 ---
 
@@ -395,7 +395,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.79.0 start ./my-spec.md
+  asklokesh/loki-mode:7.80.1 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.79.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
+var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.80.1";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -793,4 +793,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write($Q),2}}s1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var qZ=await KZ(Bun.argv.slice(2));process.exit(qZ);
 
-//# debugId=79AD90D8C0F4D86964756E2164756E21
+//# debugId=7F54054FBBA43A1E64756E2164756E21

package/lokistore/__init__.py

@@ -0,0 +1,65 @@
+"""
+LokiStore: pluggable, local-first storage abstraction for Loki Mode.
+
+This package is the consolidation spine for durable artifacts (state,
+checkpoints, memory blobs, healing artifacts, etc.). Features should bind to
+this abstraction instead of hardcoding `.loki/` paths or embedding their own
+cloud SDK clients.
+
+Design goals
+------------
+- Local-first by default. With nothing configured, LocalStore writes to the
+  project `.loki/` directory with byte-identical behavior to today's direct
+  file writes (atomic temp+rename, fcntl advisory locking, path-traversal
+  guard). Zero new dependencies, zero behavior change for local users.
+- Optional cloud backends (S3, GCS, Azure Blob) behind lazy imports. The
+  cloud SDK is imported ONLY inside the backend's __init__, so a missing
+  dependency raises a clear, actionable error ONLY when that backend is
+  explicitly selected -- never at import time, never for local users.
+- One interface (put/get/get_to/exists/list/delete) so callers are backend
+  agnostic.
+
+Quick start
+-----------
+    from lokistore import get_store
+
+    store = get_store()  # local by default, honors LOKI_DIR/TARGET_DIR
+    store.put("state/checkpoints/cp-1/metadata.json", b"{...}")
+    data = store.get("state/checkpoints/cp-1/metadata.json")
+    for key in store.list("state/checkpoints/"):
+        ...
+
+Configuration (env or config dict)
+----------------------------------
+- LOKI_STORAGE_BACKEND : local | s3 | gcs | azure-blob   (default: local)
+- LOKI_STORAGE_BUCKET  : bucket / container name          (cloud backends)
+- LOKI_STORAGE_PREFIX  : key prefix within the bucket      (optional)
+- LOKI_STORAGE_REGION  : region                            (s3, optional)
+
+The metadata backend (sqlite default, postgres later) is selected separately;
+see get_metadata_backend() / METADATA notes below. For this release the blob
+backends are the core deliverable and the metadata selector is a thin,
+documented stub that defaults to the existing sqlite path.
+"""
+
+from .base import LokiStore, StoreError, BackendNotAvailableError
+from .local import LocalStore
+from .factory import (
+    get_store,
+    build_store,
+    get_metadata_backend,
+    resolve_local_base,
+)
+
+__all__ = [
+    "LokiStore",
+    "StoreError",
+    "BackendNotAvailableError",
+    "LocalStore",
+    "get_store",
+    "build_store",
+    "get_metadata_backend",
+    "resolve_local_base",
+]
+
+__version__ = "1.0.0"

package/lokistore/base.py

@@ -0,0 +1,172 @@
+"""
+LokiStore interface and shared helpers.
+
+Defines the abstract blob-store contract that every backend implements, plus
+errors and a key-normalization helper shared across backends.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import List, Union
+
+
+class StoreError(Exception):
+    """Base class for LokiStore errors."""
+
+
+class BackendNotAvailableError(StoreError):
+    """
+    Raised when a cloud backend is explicitly selected but its SDK (or
+    required configuration) is not available. The message names the missing
+    package and how to install it so the failure is actionable.
+    """
+
+
+def normalize_key(key: str) -> str:
+    """
+    Normalize a store key to a clean POSIX-style relative path.
+
+    Keys are relative paths like "state/checkpoints/cp-1/metadata.json".
+    This rejects absolute paths and any key that would traverse outside the
+    store root (a leading or embedded ".." segment). The same guard is used
+    by every backend so traversal is rejected uniformly, whether the bytes
+    land on a local filesystem or in an object-store key namespace.
+
+    Args:
+        key: A POSIX-style relative path.
+
+    Returns:
+        The normalized key (forward slashes, no leading slash, no "."/".."
+        segments collapsed away).
+
+    Raises:
+        ValueError: If the key is empty, absolute, or escapes the root.
+    """
+    if not isinstance(key, str) or not key:
+        raise ValueError("store key must be a non-empty string")
+
+    # Treat backslashes as separators too, so a Windows-style key cannot
+    # smuggle a traversal past the split() check below.
+    candidate = key.replace("\\", "/")
+
+    if candidate.startswith("/"):
+        raise ValueError(f"absolute keys are not allowed: {key!r}")
+
+    parts: List[str] = []
+    for segment in candidate.split("/"):
+        if segment == "" or segment == ".":
+            # Collapse empty (e.g. "a//b") and current-dir segments.
+            continue
+        if segment == "..":
+            raise ValueError(f"path traversal is not allowed in key: {key!r}")
+        parts.append(segment)
+
+    if not parts:
+        raise ValueError(f"key resolves to an empty path: {key!r}")
+
+    return "/".join(parts)
+
+
+def read_source_bytes(data: Union[bytes, bytearray, str, os.PathLike]) -> bytes:
+    """
+    Coerce a put() source argument into bytes.
+
+    Accepts raw bytes (returned as-is) or a path-like pointing at a file whose
+    contents are read in binary. A plain str is treated as a FILESYSTEM PATH,
+    not as text, to match the put(key, bytes_or_path) contract; callers that
+    want to store a string must encode it themselves.
+
+    Args:
+        data: bytes/bytearray, or a path-like to an existing file.
+
+    Returns:
+        The bytes to store.
+
+    Raises:
+        FileNotFoundError: If a path is given and the file does not exist.
+        TypeError: If the argument is neither bytes nor a path-like.
+    """
+    if isinstance(data, (bytes, bytearray)):
+        return bytes(data)
+    if isinstance(data, (str, os.PathLike)):
+        with open(data, "rb") as f:
+            return f.read()
+    raise TypeError(
+        "put() source must be bytes or a path-like to a file, "
+        f"got {type(data).__name__}"
+    )
+
+
+class LokiStore(ABC):
+    """
+    Abstract pluggable blob store.
+
+    All keys are POSIX-style relative paths (see normalize_key). Implementations
+    must apply normalize_key to every incoming key so traversal is rejected and
+    behavior is uniform across backends.
+
+    The contract is intentionally small (no streaming, no multipart, no
+    credential framework) so backends stay thin. Larger payload handling can be
+    layered on later without changing this interface.
+    """
+
+    @abstractmethod
+    def put(self, key: str, data: Union[bytes, bytearray, str, os.PathLike]) -> None:
+        """
+        Store bytes under key. The source is either raw bytes or a path-like
+        to a file whose contents are stored. Overwrites any existing value
+        atomically where the backend supports it.
+        """
+
+    @abstractmethod
+    def get(self, key: str) -> bytes:
+        """
+        Return the bytes stored under key.
+
+        Raises:
+            FileNotFoundError: If the key does not exist.
+        """
+
+    @abstractmethod
+    def get_to(self, key: str, dest_path: Union[str, os.PathLike]) -> None:
+        """
+        Write the bytes stored under key to dest_path (a local filesystem
+        path). Parent directories are created as needed.
+
+        Raises:
+            FileNotFoundError: If the key does not exist.
+        """
+
+    @abstractmethod
+    def exists(self, key: str) -> bool:
+        """Return True if key exists in the store."""
+
+    @abstractmethod
+    def list(self, prefix: str = "") -> List[str]:
+        """
+        List keys under prefix (a POSIX-style relative PATH prefix). An empty
+        prefix lists every key. Returns normalized keys, sorted, relative to
+        the store root.
+
+        Prefix semantics (portable contract):
+        - prefix is a PATH prefix matched at slash boundaries, NOT a raw
+          substring. A slash-terminated prefix like "state/" selects every key
+          beneath the "state" directory and is the portable form that behaves
+          IDENTICALLY across all backends (local and cloud).
+        - An empty prefix lists everything.
+
+        A non-slash-terminated prefix (e.g. "state") is normalized to its
+        directory form before matching, so it selects keys under "state/" and
+        does NOT match siblings that merely share the leading characters (e.g.
+        "stateful/x.json"). Callers wanting portable results should pass a
+        slash-terminated prefix.
+        """
+
+    @abstractmethod
+    def delete(self, key: str) -> bool:
+        """
+        Delete key. Returns True if a value was removed, False if the key did
+        not exist (delete is idempotent and never raises on a missing key).
+        """