@1password/sdk 0.0.0-credential-broker-dev-preview

package/README.md

@@ -0,0 +1,220 @@
+<p align="center">
+  <a href="https://1password.com">
+      <h1 align="center">1Password JavaScript SDK</h1>
+  </a>
+</p>
+
+<p align="center">
+ <h4 align="center">Build integrations that programmatically interact with 1Password.</h4>
+</p>
+
+<p align="center">
+   <a href="https://developer.1password.com/docs/sdks/">Documentation</a> | <a href="https://github.com/1Password/onepassword-sdk-js/tree/main/examples">Examples</a>
+<br/>
+
+---
+
+## 🚀 Get started
+
+You can choose between two [authentication methods](https://developer.1password.com/docs/sdks/concepts#authentication) for the 1Password JavaScript SDK: local authorization prompts from the [1Password desktop app](#option-1-1password-desktop-app) or automated authentication with a [1Password Service Account](#option-2-1password-service-account).
+
+### Option 1: 1Password desktop app
+
+[1Password desktop app authentication](https://developer.1password.com/docs/sdks/concepts#1password-desktop-app) is best for local integrations that require minimal setup from end users and sensitive workflows that require human-in-the-loop approval. 
+
+1. Install the [1Password desktop app](https://1password.com/downloads/) and sign in to your account in the app.
+2. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **Developer**.
+3. Under Integrate with the 1Password SDKs, select **Integrate with other apps**.
+4. If you want to authenticate with biometrics, navigate to **Settings** > **Security**, then turn on the option to unlock using [Touch ID](https://support.1password.com/touch-id-mac/),  [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/).
+5. Install the 1Password JavaScript SDK in your project:
+
+   ```bash
+   ## NPM
+   npm install @1password/sdk
+   ```
+
+   ```bash
+   ## PNPM
+   pnpm add @1password/sdk
+   ```
+
+   ```bash
+   ## Yarn
+   yarn add @1password/sdk
+
+6. To use the Javascript SDK in your project, replace `your-account-name` in the code below with the name of your 1Password account as it appears at the top left sidebar of the 1Password desktop app.
+
+```js
+const sdk = require("@1password/sdk");
+
+async function main() {
+  // Creates an authenticated client.
+  const client = await sdk.createClient({
+    auth: new sdk.DesktopAuth("your-account-name"),
+    // Set the following to your own integration name and version.
+    integrationName: "My 1Password Integration",
+    integrationVersion: "v1.0.0",
+  });
+
+  // Fetches a secret.
+  const secret = await client.secrets.resolve("op://vault/item/field");
+}
+
+main()
+```
+
+Inside `createClient()`, set `integrationName` to the name of your application and `integrationVersion` to the version of your application.
+
+Make sure to use [secret reference URIs](https://developer.1password.com/docs/cli/secret-reference-syntax/) with the syntax `op://vault/item/field` to securely load secrets from 1Password into your code.
+
+### Option 2: 1Password Service Account
+
+[Service account authentication](https://developer.1password.com/docs/sdks/concepts/#1password-service-account) is best for automated access and limiting your integration to least privilege access.
+
+1. [Create a service account](https://my.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=github-sdk) and give it the appropriate permissions in the vaults where the items you want to use with the SDK are saved.
+2. Provision your service account token. We recommend provisioning your token from the environment. For example, to export your token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable:
+
+   **macOS or Linux**
+
+   ```bash
+   export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
+   ```
+
+   **Windows**
+
+   ```powershell
+   $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>"
+   ```
+
+3. Install the 1Password JavaScript SDK in your project:
+
+   ```bash
+   ## NPM
+   npm install @1password/sdk
+   ```
+
+   ```bash
+   ## PNPM
+   pnpm add @1password/sdk
+   ```
+
+   ```bash
+   ## Yarn
+   yarn add @1password/sdk
+   ```
+
+4. Use the JavaScript SDK in your project:
+
+```js
+const sdk = require("@1password/sdk");
+
+async function main() {
+  // Creates an authenticated client.
+  const client = await sdk.createClient({
+    auth: process.env.OP_SERVICE_ACCOUNT_TOKEN,
+    // Set the following to your own integration name and version.
+    integrationName: "My 1Password Integration",
+    integrationVersion: "v1.0.0",
+  });
+
+  // Fetches a secret.
+  const secret = await client.secrets.resolve("op://vault/item/field");
+}
+
+main()
+```
+
+Make sure to use [secret reference URIs](https://developer.1password.com/docs/cli/secret-reference-syntax/) with the syntax `op://vault/item/field` to securely load secrets from 1Password into your code.
+
+Inside `createClient()`, set `integrationName` to the name of your application and `integrationVersion` to the version of your application.
+
+## Supported functionality
+
+1Password SDKs are in active development. We're keen to hear what you'd like to see next. Let us know by [upvoting](https://github.com/1Password/onepassword-sdk-js/issues) or [filing](https://github.com/1Password/onepassword-sdk-js/issues/new/choose) an issue.
+
+### Item management
+
+**Operations:**
+
+- [x] [Retrieve secrets](https://developer.1password.com/docs/sdks/load-secrets)
+- [Read 1Password Environments (beta)](https://developer.1password.com/docs/sdks/environments)
+- [x] [Retrieve items](https://developer.1password.com/docs/sdks/manage-items#get-an-item)
+- [x] [Create items](https://developer.1password.com/docs/sdks/manage-items#create-an-item)
+- [x] [Update items](https://developer.1password.com/docs/sdks/manage-items#update-an-item)
+- [x] [Delete items](https://developer.1password.com/docs/sdks/manage-items#delete-an-item)
+- [x] [Archive items](https://developer.1password.com/docs/sdks/manage-items/#archive-an-item)
+- [x] [List items](https://developer.1password.com/docs/sdks/list-vaults-items/)
+- [x] [Share items](https://developer.1password.com/docs/sdks/share-items)
+- [x] [Generate PIN, random and memorable passwords](https://developer.1password.com/docs/sdks/manage-items#generate-a-password)
+
+**Field types:**
+
+- [x] API Keys
+- [x] Passwords
+- [x] Concealed fields
+- [x] Text fields
+- [x] Notes
+- [x] SSH private keys, public keys, fingerprint and key type
+- [x] One-time passwords
+- [x] URLs
+- [x] Websites (used to suggest and autofill logins)
+- [x] Phone numbers
+- [x] Credit card types
+- [x] Credit card numbers
+- [x] Emails
+- [x] References to other items
+- [x] Address
+- [x] Date
+- [x] MM/YY
+- [x] File attachments and Document items
+- [x] Menu
+- [ ] Passkeys
+
+### Vault management
+
+- [x] [Retrieve vaults](https://developer.1password.com/docs/sdks/vaults#get-a-vault-overview)
+- [x] [Create vaults](https://developer.1password.com/docs/sdks/vaults#create-a-vault)
+- [x] [Update vaults](https://developer.1password.com/docs/sdks/vaults#update-a-vault)
+- [x] [Delete vaults](https://developer.1password.com/docs/sdks/vaults#delete-a-vault)
+- [x] [List vaults](https://developer.1password.com/docs/sdks/list-vaults-items#list-vaults)
+- [x] [Manage group vault permissions](https://developer.1password.com/docs/sdks/vault-permissions)
+- [ ] Manage user vault permissions
+
+### User & access management
+
+- [ ] Provision users
+- [ ] Retrieve users
+- [ ] List users
+- [ ] Suspend users
+- [x] [Retrieve groups](https://developer.1password.com/docs/sdks/groups/)
+- [ ] List groups
+- [ ] Create groups
+- [ ] Update group membership
+
+## Environments management
+
+- [x] [Read 1Password Environments](/docs/sdks/environments) (beta)
+
+### Compliance & reporting
+
+- [ ] Watchtower insights
+- [ ] Travel mode
+- [ ] Events. For now, use [1Password Events Reporting API](https://developer.1password.com/docs/events-api/) directly.
+
+### Authentication
+
+- [x] [1Password Service Accounts](https://developer.1password.com/docs/sdks/concepts#1password-service-account)
+- [x] [User authentication](https://developer.1password.com/docs/sdks/concepts#1password-desktop-app)
+- [ ] 1Password Connect. For now, use [1Password/connect-sdk-js](https://github.com/1Password/connect-sdk-js).
+
+## 📖 Learn more
+
+- [Load secrets](https://developer.1password.com/docs/sdks/load-secrets)
+- [Manage items](https://developer.1password.com/docs/sdks/manage-items)
+- [Manage files](https://developer.1password.com/docs/sdks/files)
+- [Share items](https://developer.1password.com/docs/sdks/share-items)
+- [List vaults and items](https://developer.1password.com/docs/sdks/list-vaults-items)
+- [Manage vaults](https://developer.1password.com/docs/sdks/vaults)
+- [Manage vault permissions](https://developer.1password.com/docs/sdks/vault-permissions)
+- [Manage groups](https://developer.1password.com/docs/sdks/groups)
+- [1Password SDK concepts](https://developer.1password.com/docs/sdks/concepts)

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import { InnerClient } from "./core.js";
+import { SecretsApi } from "./secrets.js";
+import { ItemsApi } from "./items.js";
+import { VaultsApi } from "./vaults.js";
+import { EnvironmentsApi } from "./environments.js";
+import { GroupsApi } from "./groups.js";
+import { CredentialBrokerApi, OAuthCredentialBrokerApi } from "./credential_broker.js";
+export declare class Client {
+    secrets: SecretsApi;
+    items: ItemsApi;
+    vaults: VaultsApi;
+    environments: EnvironmentsApi;
+    groups: GroupsApi;
+    constructor(innerClient: InnerClient);
+}
+export declare class OidcClient {
+    credentialBroker: CredentialBrokerApi;
+    constructor(innerClient: InnerClient);
+}
+export declare class OAuthClient {
+    credentialBroker: OAuthCredentialBrokerApi;
+    constructor(innerClient: InnerClient);
+}

package/dist/client.js

@@ -0,0 +1,32 @@
+"use strict";
+// Code generated by op-codegen - DO NOT EDIT MANUALLY
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthClient = exports.OidcClient = exports.Client = void 0;
+const secrets_js_1 = require("./secrets.js");
+const items_js_1 = require("./items.js");
+const vaults_js_1 = require("./vaults.js");
+const environments_js_1 = require("./environments.js");
+const groups_js_1 = require("./groups.js");
+const credential_broker_js_1 = require("./credential_broker.js");
+class Client {
+    constructor(innerClient) {
+        this.secrets = new secrets_js_1.Secrets(innerClient);
+        this.items = new items_js_1.Items(innerClient);
+        this.vaults = new vaults_js_1.Vaults(innerClient);
+        this.environments = new environments_js_1.Environments(innerClient);
+        this.groups = new groups_js_1.Groups(innerClient);
+    }
+}
+exports.Client = Client;
+class OidcClient {
+    constructor(innerClient) {
+        this.credentialBroker = new credential_broker_js_1.CredentialBroker(innerClient);
+    }
+}
+exports.OidcClient = OidcClient;
+class OAuthClient {
+    constructor(innerClient) {
+        this.credentialBroker = new credential_broker_js_1.OAuthCredentialBroker(innerClient);
+    }
+}
+exports.OAuthClient = OAuthClient;

package/dist/client_builder.d.ts

@@ -0,0 +1,18 @@
+import { SharedCore } from "./core.js";
+import { ClientConfiguration, OidcClientConfiguration, OAuthClientConfiguration } from "./configuration.js";
+import { Client, OAuthClient, OidcClient } from "./client.js";
+/**
+ * Creates a 1Password SDK client with a given core implementation.
+ * @returns The authenticated 1Password SDK client.
+ */
+export declare const createClientWithCore: (config: ClientConfiguration, core: SharedCore) => Promise<Client>;
+/**
+ * Creates a 1Password OIDC client with a given core implementation.
+ * @returns The authenticated 1Password OIDC client.
+ */
+export declare const createOidcClientWithCore: (config: OidcClientConfiguration, core: SharedCore) => Promise<OidcClient>;
+/**
+ * Creates a 1Password OAuth client with a given core implementation.
+ * @returns The authenticated 1Password OAuth client.
+ */
+export declare const createOAuthClientWithCore: (config: OAuthClientConfiguration, core: SharedCore) => Promise<OAuthClient>;

package/dist/client_builder.js

@@ -0,0 +1,64 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOAuthClientWithCore = exports.createOidcClientWithCore = exports.createClientWithCore = void 0;
+const core_js_1 = require("./core.js");
+const configuration_js_1 = require("./configuration.js");
+const client_js_1 = require("./client.js");
+const shared_lib_core_js_1 = require("./shared_lib_core.js");
+const finalizationRegistry = new FinalizationRegistry((heldClient) => {
+    heldClient.core.releaseClient(heldClient.id);
+});
+/**
+ * Creates a 1Password SDK client with a given core implementation.
+ * @returns The authenticated 1Password SDK client.
+ */
+const createClientWithCore = (config, core) => __awaiter(void 0, void 0, void 0, function* () {
+    const authConfig = (0, configuration_js_1.clientAuthConfig)(config);
+    if (authConfig.accountName) {
+        core.setInner(new shared_lib_core_js_1.SharedLibCore(authConfig.accountName));
+    }
+    const clientId = yield core.initClient(authConfig);
+    const inner = new core_js_1.StandardClient(parseInt(clientId, 10), core, authConfig);
+    const client = new client_js_1.Client(inner);
+    // Cleans up associated memory from core when client instance goes out of scope.
+    finalizationRegistry.register(client, inner);
+    return client;
+});
+exports.createClientWithCore = createClientWithCore;
+/**
+ * Creates a 1Password OIDC client with a given core implementation.
+ * @returns The authenticated 1Password OIDC client.
+ */
+const createOidcClientWithCore = (config, core) => __awaiter(void 0, void 0, void 0, function* () {
+    const clientId = yield core.initClientOidc(config, config.oidcFetcher);
+    const inner = new core_js_1.InnerClient(parseInt(clientId, 10), core);
+    const client = new client_js_1.OidcClient(inner);
+    // Cleans up associated memory from core when client instance goes out of scope.
+    finalizationRegistry.register(client, inner);
+    return client;
+});
+exports.createOidcClientWithCore = createOidcClientWithCore;
+/**
+ * Creates a 1Password OAuth client with a given core implementation.
+ * @returns The authenticated 1Password OAuth client.
+ */
+const createOAuthClientWithCore = (config, core) => __awaiter(void 0, void 0, void 0, function* () {
+    // ClientConfig is untagged in the Rust core. Passing only integrationKey and
+    // accessToken to init_client selects its ClientConfig::Oauth variant.
+    const clientId = yield core.initClient(config);
+    const inner = new core_js_1.InnerClient(parseInt(clientId, 10), core);
+    const client = new client_js_1.OAuthClient(inner);
+    // Cleans up associated memory from core when client instance goes out of scope.
+    finalizationRegistry.register(client, inner);
+    return client;
+});
+exports.createOAuthClientWithCore = createOAuthClientWithCore;

package/dist/configuration.d.ts

@@ -0,0 +1,33 @@
+import { ClientAuthConfig, WorkloadDetails } from "./core.js";
+export declare const LANGUAGE = "JS";
+export declare const VERSION = "0000000";
+interface BaseClientConfiguration {
+    integrationName: string;
+    integrationVersion: string;
+}
+export interface ClientConfiguration extends BaseClientConfiguration {
+    auth: Auth;
+}
+export interface OidcClientConfiguration extends BaseClientConfiguration {
+    oidcFetcher: (audience: string) => Promise<string>;
+    workloadDetails: WorkloadDetails;
+}
+export interface OAuthClientConfiguration {
+    accessToken: string;
+    integrationKey: string;
+}
+type Auth = string | DesktopAuth;
+/**
+ * Setting that specifies a client should use the desktop app to authenticate. Set accountName to your 1Password account name as shown at the top left sidebar of the app, or your account UUID.
+ */
+export declare class DesktopAuth {
+    accountName: string;
+    constructor(accountName: string);
+}
+/**
+ * Creates a default client configuration.
+ * @returns The client configuration to instantiate the client with.
+ */
+export declare const clientAuthConfig: (userConfig: ClientConfiguration) => ClientAuthConfig;
+export declare const getOsName: () => string;
+export {};

package/dist/configuration.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOsName = exports.clientAuthConfig = exports.DesktopAuth = exports.VERSION = exports.LANGUAGE = void 0;
+const os_1 = __importDefault(require("os"));
+const version_js_1 = require("./version.js");
+exports.LANGUAGE = "JS";
+exports.VERSION = version_js_1.SDK_BUILD_NUMBER;
+/**
+ * Setting that specifies a client should use the desktop app to authenticate. Set accountName to your 1Password account name as shown at the top left sidebar of the app, or your account UUID.
+ */
+class DesktopAuth {
+    constructor(accountName) {
+        this.accountName = accountName;
+    }
+}
+exports.DesktopAuth = DesktopAuth;
+/**
+ * Creates a default client configuration.
+ * @returns The client configuration to instantiate the client with.
+ */
+const clientAuthConfig = (userConfig) => {
+    // TODO: Add logic for computing the correct sanitized version value for each platform
+    const defaultOsVersion = "0.0.0";
+    let serviceAccountToken;
+    let accountName;
+    if (typeof userConfig.auth === "string") {
+        serviceAccountToken = userConfig.auth;
+    }
+    else if (userConfig.auth instanceof DesktopAuth) {
+        accountName = userConfig.auth.accountName;
+    }
+    return {
+        serviceAccountToken: serviceAccountToken !== null && serviceAccountToken !== void 0 ? serviceAccountToken : "",
+        accountName,
+        programmingLanguage: exports.LANGUAGE,
+        sdkVersion: exports.VERSION,
+        integrationName: userConfig.integrationName,
+        integrationVersion: userConfig.integrationVersion,
+        requestLibraryName: "Fetch API",
+        requestLibraryVersion: "Fetch API",
+        os: (0, exports.getOsName)(),
+        osVersion: defaultOsVersion,
+        architecture: os_1.default.arch(),
+    };
+};
+exports.clientAuthConfig = clientAuthConfig;
+const getOsName = () => {
+    // Only supported on Node.js
+    const os_name = os_1.default.type().toLowerCase();
+    if (os_name === "windows_nt") {
+        return "windows";
+    }
+    return os_name;
+};
+exports.getOsName = getOsName;

package/dist/core.d.ts

@@ -0,0 +1,115 @@
+import type { OidcClientConfiguration, OAuthClientConfiguration } from "./configuration.js";
+/**
+ *  Exposes the SDK core to the host JS SDK.
+ */
+export interface Core {
+    /**
+     *  Allocates a new authenticated client and returns its id.
+     */
+    initClient(config: string): Promise<string>;
+    /**
+     *  Allocates a new authenticated client using an OIDC token fetcher and returns its id.
+     */
+    initClientOidc(config: string, fetcher: (audience: string) => Promise<string>): Promise<string>;
+    /**
+     *  Calls async business logic from a given client and returns the result.
+     */
+    invoke(config: string): Promise<string>;
+    /**
+     *  Deallocates memory held by the given client in the SDK core when it goes out of scope.
+     */
+    releaseClient(clientId: string): void;
+}
+/**
+ *  Wraps configuration information needed to allocate and authenticate a client instance and sends it to the SDK core.
+ */
+export interface ClientAuthConfig {
+    programmingLanguage: string;
+    sdkVersion: string;
+    integrationName: string;
+    integrationVersion: string;
+    requestLibraryName: string;
+    requestLibraryVersion: string;
+    os: string;
+    osVersion: string;
+    architecture: string;
+    serviceAccountToken?: string;
+    accountName?: string;
+    workloadDetails?: WorkloadDetails;
+}
+/**
+ *  Contains workload authentication details for OIDC-based workload identity.
+ */
+export interface WorkloadDetails {
+    customerManagedSecret: string;
+    workloadUuid: string;
+}
+/**
+ *  Contains the information sent to the SDK core when you call (invoke) a function.
+ */
+export interface InvokeConfig {
+    /**
+     *  Identifies the client instance for which you called the function.
+     */
+    invocation: Invocation;
+}
+/**
+ *  Calls certain logic from the SDK core, with the given parameters.
+ */
+interface Invocation {
+    /**
+     *  Identifies the client instance for which you called the function.
+     */
+    clientId?: number;
+    parameters: Parameters;
+}
+export interface Parameters {
+    /**
+     *  Functionality name
+     */
+    name: string;
+    /**
+     *  Parameters
+     */
+    parameters: {
+        [key: string]: unknown;
+    };
+}
+export declare class WasmCore implements Core {
+    initClient(config: string): Promise<string>;
+    initClientOidc(config: string, fetcher: (audience: string) => Promise<string>): Promise<string>;
+    invoke(config: string): Promise<string>;
+    releaseClient(clientId: string): void;
+}
+/**
+ *  An implementation of the `Core` interface that shares resources across all clients.
+ */
+export declare class SharedCore {
+    private inner;
+    constructor();
+    setInner(core: Core): void;
+    initClient(config: ClientAuthConfig | OAuthClientConfiguration): Promise<string>;
+    initClientOidc(config: OidcClientConfiguration, fetcher: (audience: string) => Promise<string>): Promise<string>;
+    invoke(config: InvokeConfig): Promise<string>;
+    invoke_sync(config: InvokeConfig): string;
+    releaseClient(clientId: number): void;
+}
+/**
+ *  Represents the client instance on which a call is made.
+ */
+export declare class InnerClient {
+    id: number;
+    readonly core: SharedCore;
+    constructor(id: number, core: SharedCore);
+    invoke(config: InvokeConfig): Promise<string>;
+}
+/**
+ *  A token- or desktop-authenticated client. It retains the auth config so it can
+ *  transparently re-initialize after a desktop session expires.
+ */
+export declare class StandardClient extends InnerClient {
+    config: ClientAuthConfig;
+    constructor(id: number, core: SharedCore, config: ClientAuthConfig);
+    invoke(config: InvokeConfig): Promise<string>;
+}
+export {};