@fonoster/identity-client 0.19.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fonoster Inc
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import * as grpc from "@grpc/grpc-js";
+export interface CreateUserRequest {
+    name: string;
+    email: string;
+    password: string;
+    phone?: string;
+    avatar?: string;
+}
+export interface ExchangeCredentialsRequest {
+    username: string;
+    password: string;
+    twoFactorCode?: string;
+}
+export interface ExchangeResponse {
+    idToken?: string;
+    accessToken: string;
+    refreshToken: string;
+}
+export interface Workspace {
+    ref: string;
+    name: string;
+    ownerRef: string;
+    accessKeyId: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface WorkspaceMember {
+    ref: string;
+    userRef: string;
+    name: string;
+    email: string;
+    role: string;
+    status: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface InviteMemberRequest {
+    email: string;
+    role: string;
+    name?: string;
+}
+export interface WorkspaceAccess {
+    accessKeyId: string;
+    role: string;
+}
+/** Claims carried by an Identity-issued access token. */
+export interface AccessClaims {
+    /** User ref (JWT subject). */
+    sub: string;
+    /** The user's own access key id (US…). */
+    accessKeyId: string;
+    /** Workspaces the user can act in, with their role. */
+    access: WorkspaceAccess[];
+}
+/**
+ * Lightweight, stateless client for the Fonoster Identity gRPC service. Targets
+ * any Identity endpoint and wraps the callback-based stubs in promises.
+ *
+ * Authenticated calls accept the caller's access `token` and active `accessKeyId`
+ * per call, forwarded as gRPC metadata — so a server can act on behalf of many
+ * different callers using one client instance.
+ */
+export declare class IdentityClient {
+    private readonly client;
+    private cachedPublicKey;
+    constructor(endpoint: string, credentials?: grpc.ChannelCredentials);
+    private unary;
+    getPublicKey(): Promise<{
+        publicKey: string;
+    }>;
+    /**
+     * Verifies an Identity-issued RS256 access token using Identity's public key
+     * (fetched once via `getPublicKey` and cached). Returns the claims, or `null`
+     * when the token is missing, malformed, expired, or otherwise invalid.
+     */
+    verifyToken(token: string): Promise<AccessClaims | null>;
+    createUser(request: CreateUserRequest): Promise<{
+        ref: string;
+    }>;
+    exchangeCredentials(request: ExchangeCredentialsRequest): Promise<ExchangeResponse>;
+    exchangeRefreshToken(refreshToken: string): Promise<ExchangeResponse>;
+    createWorkspace(name: string, token: string): Promise<{
+        ref: string;
+    }>;
+    listWorkspaces(token: string): Promise<{
+        items: Workspace[];
+        nextPageToken?: string;
+    }>;
+    getWorkspace(ref: string, token: string): Promise<Workspace>;
+    updateWorkspace(ref: string, name: string, token: string): Promise<{
+        ref: string;
+    }>;
+    listWorkspaceMembers(accessKeyId: string, token: string): Promise<{
+        items: WorkspaceMember[];
+        nextPageToken?: string;
+    }>;
+    inviteUserToWorkspace(request: InviteMemberRequest, accessKeyId: string, token: string): Promise<{
+        userRef: string;
+    }>;
+    removeUserFromWorkspace(userRef: string, accessKeyId: string, token: string): Promise<{
+        userRef: string;
+    }>;
+    resendWorkspaceMembershipInvitation(userRef: string, accessKeyId: string, token: string): Promise<{
+        userRef: string;
+    }>;
+    sendResetPasswordCode(username: string, resetPasswordUrl: string): Promise<void>;
+    resetPassword(username: string, password: string, verificationCode: string): Promise<void>;
+    close(): void;
+}
+/** Convenience factory. The endpoint is required — no environment-variable fallback. */
+export declare function createIdentityClient(endpoint: string, credentials?: grpc.ChannelCredentials): IdentityClient;

package/dist/index.js

@@ -0,0 +1,181 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityClient = void 0;
+exports.createIdentityClient = createIdentityClient;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const node_path_1 = require("node:path");
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const PROTO_PATH = (0, node_path_1.join)(__dirname, "..", "proto", "identity.proto");
+const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+    keepCase: false,
+    longs: String,
+    enums: String,
+    defaults: false,
+    arrays: true,
+    oneofs: true
+});
+const proto = grpc.loadPackageDefinition(packageDefinition);
+const IdentityService = proto.fonoster.identity.v1beta2.Identity;
+/**
+ * Lightweight, stateless client for the Fonoster Identity gRPC service. Targets
+ * any Identity endpoint and wraps the callback-based stubs in promises.
+ *
+ * Authenticated calls accept the caller's access `token` and active `accessKeyId`
+ * per call, forwarded as gRPC metadata — so a server can act on behalf of many
+ * different callers using one client instance.
+ */
+class IdentityClient {
+    constructor(endpoint, credentials = grpc.credentials.createInsecure()) {
+        this.cachedPublicKey = null;
+        this.client = new IdentityService(endpoint, credentials);
+    }
+    unary(method, request, meta = {}) {
+        const metadata = new grpc.Metadata();
+        if (meta.token)
+            metadata.set("token", meta.token);
+        if (meta.accessKeyId)
+            metadata.set("accesskeyid", meta.accessKeyId);
+        const client = this.client;
+        return new Promise((resolve, reject) => {
+            client[method](request, metadata, (err, res) => err ? reject(err) : resolve(res));
+        });
+    }
+    getPublicKey() {
+        return this.unary("getPublicKey", {});
+    }
+    /**
+     * Verifies an Identity-issued RS256 access token using Identity's public key
+     * (fetched once via `getPublicKey` and cached). Returns the claims, or `null`
+     * when the token is missing, malformed, expired, or otherwise invalid.
+     */
+    async verifyToken(token) {
+        try {
+            if (!this.cachedPublicKey) {
+                const { publicKey } = await this.getPublicKey();
+                this.cachedPublicKey = publicKey;
+            }
+            const decoded = jsonwebtoken_1.default.verify(token, this.cachedPublicKey, {
+                algorithms: ["RS256"]
+            });
+            if (typeof decoded === "string")
+                return null;
+            const claims = decoded;
+            if (!claims.sub || !claims.accessKeyId)
+                return null;
+            return {
+                sub: claims.sub,
+                accessKeyId: claims.accessKeyId,
+                access: claims.access ?? []
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    createUser(request) {
+        return this.unary("createUser", request);
+    }
+    exchangeCredentials(request) {
+        return this.unary("exchangeCredentials", request);
+    }
+    exchangeRefreshToken(refreshToken) {
+        return this.unary("exchangeRefreshToken", { refreshToken });
+    }
+    createWorkspace(name, token) {
+        return this.unary("createWorkspace", { name }, { token });
+    }
+    listWorkspaces(token) {
+        return this.unary("listWorkspaces", {}, { token });
+    }
+    getWorkspace(ref, token) {
+        return this.unary("getWorkspace", { ref }, { token });
+    }
+    updateWorkspace(ref, name, token) {
+        return this.unary("updateWorkspace", { ref, name }, { token });
+    }
+    listWorkspaceMembers(accessKeyId, token) {
+        return this.unary("listWorkspaceMembers", {}, { token, accessKeyId });
+    }
+    inviteUserToWorkspace(request, accessKeyId, token) {
+        return this.unary("inviteUserToWorkspace", request, { token, accessKeyId });
+    }
+    removeUserFromWorkspace(userRef, accessKeyId, token) {
+        return this.unary("removeUserFromWorkspace", { userRef }, { token, accessKeyId });
+    }
+    resendWorkspaceMembershipInvitation(userRef, accessKeyId, token) {
+        return this.unary("resendWorkspaceMembershipInvitation", { userRef }, { token, accessKeyId });
+    }
+    sendResetPasswordCode(username, resetPasswordUrl) {
+        return this.unary("sendResetPasswordCode", { username, resetPasswordUrl });
+    }
+    resetPassword(username, password, verificationCode) {
+        return this.unary("resetPassword", {
+            username,
+            password,
+            verificationCode
+        });
+    }
+    close() {
+        this.client.close();
+    }
+}
+exports.IdentityClient = IdentityClient;
+/** Convenience factory. The endpoint is required — no environment-variable fallback. */
+function createIdentityClient(endpoint, credentials) {
+    return new IdentityClient(endpoint, credentials);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fonoster/identity-client",
+  "version": "0.19.1",
+  "description": "Lightweight client for the Fonoster Identity gRPC service",
+  "license": "MIT",
+  "main": "dist/index",
+  "types": "dist/index",
+  "scripts": {
+    "prebuild": "rimraf ./dist tsconfig.tsbuildinfo && node scripts/sync-proto.mjs",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf ./dist node_modules tsconfig.tsbuildinfo proto"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "~1.10.6",
+    "@grpc/proto-loader": "^0.7.15",
+    "jsonwebtoken": "^9.0.2"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.9.0"
+  },
+  "files": [
+    "dist",
+    "proto"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "4c28def9ff1aebbbaf2e23a8944cf3cf49c4da1e"
+}

package/proto/identity.proto

@@ -0,0 +1,359 @@
+/*
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+syntax = "proto3";
+
+package fonoster.identity.v1beta2;
+
+import "google/protobuf/empty.proto";
+
+service Identity {
+  // Workspace actions
+  rpc CreateWorkspace (CreateWorkspaceRequest) returns (CreateWorkspaceResponse) {}
+  rpc DeleteWorkspace (DeleteWorkspaceRequest) returns (DeleteWorkspaceResponse) {}
+  rpc GetWorkspace (GetWorkspaceRequest) returns (Workspace) {}
+  rpc ListWorkspaces (ListWorkspacesRequest) returns (ListWorkspacesResponse) {}
+  rpc UpdateWorkspace (UpdateWorkspaceRequest) returns (UpdateWorkspaceResponse) {}
+  rpc InviteUserToWorkspace (InviteUserToWorkspaceRequest) returns (InviteUserToWorkspaceResponse) {}
+  rpc RemoveUserFromWorkspace (RemoveUserFromWorkspaceRequest) returns (RemoveUserFromWorkspaceResponse) {}
+  rpc ResendWorkspaceMembershipInvitation (ResendWorkspaceMembershipInvitationRequest) returns (ResendWorkspaceMembershipInvitationResponse) {}
+  rpc ListWorkspaceMembers (ListWorkspaceMembersRequest) returns (ListWorkspaceMembersResponse) {}
+
+  // User specific actions
+  rpc CreateUser (CreateUserRequest) returns (CreateUserResponse) {}
+  rpc CreateUserWithOauth2Code (CreateUserWithOauth2CodeRequest) returns (ExchangeCredentialsResponse) {}
+  rpc GetUser (GetUserRequest) returns (User) {}
+  rpc UpdateUser (UpdateUserRequest) returns (UpdateUserResponse) {}
+  rpc DeleteUser (DeleteUserRequest) returns (DeleteUserResponse) {}
+  rpc SendVerificationCode (SendVerificationCodeRequest) returns (google.protobuf.Empty) {}
+  rpc VerifyCode (VerifyCodeRequest) returns (google.protobuf.Empty) {}
+  rpc SendResetPasswordCode (SendResetPasswordCodeRequest) returns (google.protobuf.Empty) {}
+  rpc ResetPassword (ResetPasswordRequest) returns (google.protobuf.Empty) {}
+
+  // ApiKey actions
+  rpc CreateApiKey (CreateApiKeyRequest) returns (CreateApiKeyResponse) {}
+  rpc DeleteApiKey (DeleteApiKeyRequest) returns (DeleteApiKeyResponse) {}
+  rpc ListApiKeys (ListApiKeysRequest) returns (ListApiKeysResponse) {}
+  rpc RegenerateApiKey (RegenerateApiKeyRequest) returns (RegenerateApiKeyResponse) {}
+
+  // Token exchange actions
+  rpc ExchangeCredentials (ExchangeCredentialsRequest) returns (ExchangeCredentialsResponse) {}
+  rpc ExchangeApiKey (ExchangeApiKeyRequest) returns (ExchangeApiKeyResponse) {}
+  rpc ExchangeOauth2Code (ExchangeOauth2CodeRequest) returns (ExchangeOauth2CodeResponse) {}
+  rpc ExchangeRefreshToken (ExchangeRefreshTokenRequest) returns (ExchangeRefreshTokenResponse) {}
+  rpc RevokeToken (RevokeTokenRequest) returns (RevokeTokenResponse) {}
+
+  // Get the public key for verifying JWTs
+  rpc GetPublicKey (google.protobuf.Empty) returns (GetPublicKeyResponse) {}
+}
+
+// Workspace Resources
+
+message Workspace {
+  message Owner {
+    string ref = 1;
+    string name = 2;
+    string email = 3;
+  }
+
+  string ref = 1;
+  string name = 2;
+  string owner_ref = 3;
+  string access_key_id = 4;
+  int32 created_at = 5;
+  int32 updated_at = 6;
+  Owner owner = 7;
+}
+
+message CreateWorkspaceRequest {
+  string name = 1;
+}
+
+message CreateWorkspaceResponse {
+  string ref = 1;
+}
+
+message DeleteWorkspaceRequest {
+  string ref = 1;
+}
+
+message DeleteWorkspaceResponse {
+  string ref = 1;
+}
+
+message GetWorkspaceRequest {
+  string ref = 1;
+}
+
+message ListWorkspacesRequest {
+  string page_token = 1;
+  int32 page_size = 2;
+}
+
+message ListWorkspacesResponse {
+  repeated Workspace items = 1;
+  string next_page_token = 2;
+}
+
+message UpdateWorkspaceRequest {
+  string ref = 1;
+  string name = 2;
+}
+
+message UpdateWorkspaceResponse {
+  string ref = 1;
+}
+
+message InviteUserToWorkspaceRequest {
+  string email = 1;
+  string role = 2;
+  string name = 3;
+}
+
+message InviteUserToWorkspaceResponse {
+  string user_ref = 1;
+}
+
+message RemoveUserFromWorkspaceRequest {
+  string user_ref = 1;
+}
+
+message RemoveUserFromWorkspaceResponse {
+  string user_ref = 1;
+}
+
+message ResendWorkspaceMembershipInvitationRequest {
+  string user_ref = 1;
+}
+
+message ResendWorkspaceMembershipInvitationResponse {
+  string user_ref = 1;
+}
+
+message WorkspaceMember {
+  string ref = 1;
+  string user_ref = 2;
+  string name = 3;
+  string email = 4;
+  string role = 5;
+  string status = 6;
+  int32 created_at = 7;
+  int32 updated_at = 8;
+}
+
+message ListWorkspaceMembersRequest {
+  string page_token = 1;
+  int32 page_size = 2;
+}
+
+message ListWorkspaceMembersResponse {
+  repeated WorkspaceMember items = 1;
+  string next_page_token = 2;
+}
+
+// User Resources
+enum ContactType {
+  EMAIL = 0;
+  PHONE = 1;
+}
+
+message CreateUserRequest {
+  string email = 1;
+  string phone = 5;
+  string password = 2;
+  string name = 3;
+  string avatar = 4;
+}
+
+message CreateUserResponse {
+  string ref = 1;
+}
+
+message CreateUserWithOauth2CodeRequest {
+  string code = 1;
+}
+
+message GetUserRequest {
+  string ref = 1;
+}
+
+message User {
+  string ref = 1;
+  string email = 2;
+  string phone = 7;
+  string name = 3;
+  string avatar = 4;
+  int32 created_at = 5;
+  int32 updated_at = 6;
+}
+
+message UpdateUserRequest {
+  string ref = 1;
+  string password = 2;
+  string name = 3;
+  string avatar = 4;
+  string phone = 5;
+}
+
+message UpdateUserResponse {
+  string ref = 1;
+}
+
+message DeleteUserRequest {
+  string ref = 1;
+}
+
+message DeleteUserResponse {
+  string ref = 1;
+}
+
+message SendVerificationCodeRequest {
+  ContactType contact_type = 1;
+  string value = 2;
+}
+
+message VerifyCodeRequest {
+  string username = 1;
+  ContactType contact_type = 2;
+  string value = 3;
+  string verification_code = 4;
+}
+
+message SendResetPasswordCodeRequest {
+  string username = 1;
+  string reset_password_url = 2;
+}
+
+message ResetPasswordRequest {
+  string username = 1;
+  string password = 2;
+  string verification_code = 3;
+}
+
+// ApiKey Resources
+
+message CreateApiKeyRequest {
+  string role = 1;
+  int32 expires_at = 2;
+}
+
+message CreateApiKeyResponse {
+  string ref = 1;
+  string access_key_id = 2;
+  string access_key_secret = 3;
+}
+
+message DeleteApiKeyRequest {
+  string ref = 1;
+}
+
+message DeleteApiKeyResponse {
+  string ref = 1;
+}
+
+message ListApiKeysRequest {
+  string page_token = 1;
+  int32 page_size = 2;
+}
+
+message ListApiKeysResponse {
+  repeated ApiKey items = 1;
+  string next_page_token = 2;
+}
+
+message RegenerateApiKeyRequest {
+  string ref = 1;
+}
+
+message RegenerateApiKeyResponse {
+  string ref = 1;
+  string access_key_id = 2;
+  string access_key_secret = 3;
+}
+
+message ApiKey {
+  string ref = 1;
+  string access_key_id = 2;
+  string role = 3;
+  int32 expires_at = 4;
+  int32 created_at = 5;
+  int32 updated_at = 6;
+}
+
+// Token Exchange Resources
+
+message ExchangeCredentialsRequest {
+  string username = 1;
+  string password = 2;
+  // Required only if the 2FA feature flag is enabled 
+  string two_factor_code = 3;
+}
+
+message ExchangeCredentialsResponse {
+  string id_token = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+}
+
+message ExchangeApiKeyRequest {
+  string access_key_id = 1;
+  string access_key_secret = 2;
+}
+
+message ExchangeApiKeyResponse {
+  string id_token = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+}
+
+message ExchangeOauth2CodeRequest {
+  enum Oauth2Provider {
+    GITHUB = 0;
+  }
+  Oauth2Provider provider = 1;
+  string code = 2;
+}
+
+message ExchangeOauth2CodeResponse {
+  string id_token = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+}
+
+message ExchangeRefreshTokenRequest {
+  string refresh_token = 1;
+}
+
+message ExchangeRefreshTokenResponse {
+  string id_token = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+}
+
+message RevokeTokenRequest {
+  string token = 1;
+}
+
+message RevokeTokenResponse {
+  string token = 1;
+}
+
+// Message with response with the public key
+message GetPublicKeyResponse {
+  string public_key = 1;
+}