@vantageos/cloud-identity 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,82 @@
 All notable changes to `@vantageos/cloud-identity` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0]
+
+**Additive.** Two new primitives so one identity layer covers both deployment
+shapes and the human sign-in path — no separate self-host layer, no change to
+the Cloud/machine path. Serves Tau's `vantage-starter` self-host install and
+the Hephaistos human-path onboarding, both stalled on this surface.
+
+### Added
+
+- **Named deployment mode** — `DeploymentMode` (`"cloud" | "self-host"`) and a
+  `{ kind: "self-host"; tenantId }` branch on `TenantSource` / `requireTenantId`
+  (`src/org-guard.ts`). `cloud` keeps the existing fail-closed behaviour
+  unchanged (org/workspace required on every request — invariant #1123 holds,
+  0.4.0 reopens nothing). `self-host` is single-tenant: `requireTenantId`
+  returns the configured `tenantId` only when it is a non-empty string, and
+  **throws** otherwise — the tenant is presented explicitly by configuration,
+  never inferred from the absence of an organization.
+- **Human-path resolver** — `normalizeVerifiedHumanSession()` (`src/human-path.ts`,
+  new `./human-path` subpath export) maps an already-*verified*, framework-agnostic
+  Clerk-shaped session (`{ orgId, userId, orgRole }`) to
+  `{ tenant, subject, role }`. `role` is a new union `HumanAccountRole`
+  (`owner | admin | member | client`), distinct from `workspaceRoleSchema`
+  (`Admin | Editor | Viewer`) and never conflated. No Clerk SDK is imported.
+  Refuses (throws) on no session, no org, no user id, or an unrecognized/absent
+  org role — presented, never inferred. **Naming fix, still pre-publish:** this
+  function was originally named `resolveHumanIdentity`, which invited passing
+  in an unverified, client-supplied object (e.g. `req.body`) and would make
+  that object the trusted source of tenant/subject/role — a
+  privilege-escalation risk. Renamed to `normalizeVerifiedHumanSession` before
+  0.4.0 reaches npm (current published latest is 0.3.0) to make the
+  already-verified precondition explicit at the call-site, mirroring
+  `decodeUnverifiedBearer`'s rename from `resolveBearer` in 0.2.0. Not a
+  breaking change — 0.4.0 has no npm consumer yet.
+
+### Notes
+
+- Purely additive: every 0.3.0 export (`passesScopeFilter`, `scopeFilterList`,
+  `scopeFilterGet`, `validateMasterBearer`, `getEffectiveTenantId`,
+  `decodeUnverifiedBearer`, `requireTenantId`'s `session`/`bearer` branches, …)
+  is behaviorally unchanged. Full suite 87/87, `tsc --noEmit` 0.
+
+## [Unreleased] - 0.3.0
+
+**BREAKING.** Closes two measured 0.2.0 defects — a right must never be
+granted by absence.
+
+### Changed (breaking)
+
+- `passesScopeFilter`, `scopeFilterList`, `scopeFilterGet`, `isMasterScope`,
+  `isWildcardScope`: `oauthCtx` is now **mandatory** (`OAuthCtx`, no longer
+  `OAuthCtx | undefined`). The 0.2.0 behaviour of an omitted `oauthCtx`
+  silently passing every row (wildcard, as if master-scoped) is removed.
+  Omitting the argument now breaks the caller's build; at runtime (for
+  callers that bypass TypeScript) it throws instead of granting access.
+  Callers that deliberately want the old legacy-bearer wildcard behaviour
+  must import and pass the new `LEGACY_WILDCARD_CTX` sentinel explicitly.
+
+### Added
+
+- `LEGACY_WILDCARD_CTX` — explicit, by-name opt-in for the pre-0.3.0
+  legacy-bearer wildcard behaviour (`src/scope-filter.ts`).
+- `requireTenantId(source: TenantSource): string` — organization/workspace
+  membership guard, unifying the human (session) and machine (bearer) entry
+  paths behind one contract. Refuses on missing session, missing/empty `orgId`, and
+  missing/empty bearer-resolved `workspaceId` (`src/org-guard.ts`).
+- `SessionIdentity`, `TenantSource` types.
+
+### Scope note
+
+The package now exposes, behind one contract, all four primitives an
+application needs and should never reimplement: tenant resolution
+(`getEffectiveTenantId`), membership requirement (`requireTenantId`), row
+filtering (`passesScopeFilter` / `scopeFilterList` / `scopeFilterGet`), and
+identifier validation (`validateMasterBearer`). Framework adapters (Convex,
+Hono, etc.) wrap these; they must not reimplement the checks.
+
 ## [0.2.0] - 2026-06-13
 
 Additive release — domain-tenancy layer. No breaking changes. All 0.1.0 exports unchanged.
@@ -38,5 +114,5 @@ Initial release.
 - Public type surface: `OAuthCtx`, `ScopeProfile`, `NamespacePrefix`, `FromAllowListEntry`, `ValidateMasterBearerResult`.
 
 ### Notes
-- `getEffectiveWorkspaceId` deferred to 0.2.0 (depends on `vantageos-crm` workspace helper, owned by Theta).
+- `getEffectiveWorkspaceId` deferred to 0.2.0.
 - No `provenance: true` in `publishConfig` — provenance only from CI per fleet friction lesson `npm-publish-provenance-only-from-ci-not-local-host`.

package/LICENSE

@@ -1,21 +1,110 @@
-MIT License
+Functional Source License, Version 1.1, Apache 2.0 Future License
 
-Copyright (c) 2026 VantagePeers Cloud
+Abbreviation
 
-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:
+FSL-1.1-Apache-2.0
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Notice
+
+Copyright 2026 VantageOS (ElPi Corp)
+
+Terms and Conditions
+
+Licensor:             VantageOS (ElPi Corp)
+
+Licensed Work:        VantagePeers
+                      The Licensed Work is (c) 2026 VantageOS (ElPi Corp)
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the Licensed
+                      Work to third parties as a hosted or managed service
+                      where the service provides users with access to any
+                      substantial set of the features or functionality of the
+                      Licensed Work.
+
+Change Date:          2028-04-03 (two years from publication)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: contact@vantageos.com
+
+License text below is provided for informational purposes only.
+
+---
+
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+1. Purpose
+
+This license gives you broad permission to use, modify, and share this
+software, with one important condition: you may not use it to compete with us.
+
+2. Acceptance
+
+To use the software, you must agree to these terms. If you do not agree, you
+may not use the software.
+
+3. Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-
+sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+4. Limitations
+
+You may not make the functionality of the software available to third parties
+as a service, or otherwise use the software to provide a service to third
+parties that competes with the licensor.
+
+5. Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license or becomes able to license, to make, have made, use, sell, offer for
+sale, import, and have imported the software, in each case subject to the
+limitations and conditions in this license.
+
+6. Fair Use
+
+This license is not intended to limit any rights you may have under applicable
+fair use or other laws.
+
+7. No Other Rights
+
+These terms do not grant any other rights. The licensor reserves all rights not
+expressly granted.
+
+8. Termination
+
+Your license is automatically terminated if you violate the terms. However, if
+you cure the violation within 30 days of discovering it, your license is
+reinstated retroactively.
+
+9. Disclaimer
 
 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.
+IMPLIED.
+
+10. Limitation of Liability
+
+TO THE EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY DAMAGES
+ARISING FROM THE USE OF THE SOFTWARE.
+
+11. Change Date and License
+
+After the Change Date, the licensor grants you the rights under the Change
+License.
+
+12. Definitions
+
+"Compete" means providing a product or service that is substantially similar
+to, or a replacement for, all or a significant portion of the Licensed Work.
+
+---
+
+Apache License, Version 2.0
+
+After the Change Date (2028-04-03), this software will be available under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for full text.