@sentry/junior-google 0.0.0-stage → 0.238.1

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   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.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @sentry/junior-google
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Proof of concept. Junior acts as its own Google Workspace account, for example
+`junior@sentry.io`. Junior does not use the Google credentials of the people it
+helps. Tracking issue: getsentry/junior#2063.
+
+This version supports Calendar only. Drive and Gmail are out of scope.
+
+## Surfaces
+
+- `findMeetingTimes` finds times when every attendee is free. It reads
+  free/busy data only. It never reads event titles or details.
+- `createCalendarEvent` creates an event on Junior's own calendar. It sends
+  invites and can add a Google Meet link. A retry of the same tool call returns
+  the same event. It does not create a second invite.
+- `listCalendarEvents` reads the events on one colleague's calendar. It shows
+  only what the calendar's Google sharing settings let Junior's account see.
+  A calendar shared as free/busy only shows busy blocks without titles. It
+  never returns event descriptions.
+- `updateCalendarEvent` changes the title, description, time, or attendees of
+  an event that Junior organizes. Google emails the attendees about the
+  change. Only people invited to the event can ask for a change.
+- The **Google account** page on the dashboard Admin page shows whether the
+  account is connected. Its Connect button starts Google sign-in.
+- `junior google connect` and `junior google status` are the operator CLI.
+
+## Authentication
+
+A Junior admin connects the account one time, out of band. Slack never shows
+the sign-in link, the authorization code, or any token. Junior admins are
+managed with `junior admin grant <email>`. This plugin has no admin list of its
+own.
+
+1. An admin opens **Admin → Google account** in the dashboard and selects
+   **Connect**, or runs `junior google connect`.
+2. Google sign-in opens with PKCE and a single-use state value.
+3. The admin signs in as the configured account, not as themselves.
+4. Junior checks that the identity token names the configured account. It also
+   checks that Google granted every Calendar scope. If a check fails, Junior
+   revokes the grant and stores nothing.
+5. Junior stores the refresh token in the `junior_google_accounts` table.
+
+At runtime, the `issueCredential` hook exchanges the refresh token for a
+one-hour access token. Junior applies that token only to `www.googleapis.com`
+requests from this plugin's tools. The `grantForEgress` hook denies sandbox
+commands and any request that does not match a declared operation. Thus the
+model cannot use `curl` to read Junior's calendar and skip the tool rules.
+
+If Google rejects the refresh token (`invalid_grant`), Junior deletes it. The
+tools then report that an admin must connect the account again. If the stored
+grant does not have every scope the current tools need, the tools also ask an
+admin to reconnect.
+
+## Rules in code
+
+- Junior checks and invites only people in the allowed domains. By default,
+  the allowed domain is the domain of the account email.
+- Junior adds the requester to the attendees when it knows their email.
+- Junior changes only events that it organizes, and only for a requester who
+  is invited to the event.
+- Calendar scopes are `calendar.events.freebusy`, `calendar.events.readonly`,
+  and `calendar.events.owned`. Junior also requests `openid email` to verify
+  the account during sign-in.
+
+## Setup
+
+The plugin uses the same Google OAuth client as dashboard sign-in. Each
+sign-in requests only its own scopes, so dashboard sign-in still asks only for
+identity.
+
+1. In the Google Cloud project of the dashboard OAuth client, enable the
+   Google Calendar API.
+2. On the OAuth consent screen, use user type **Internal** and add the
+   Calendar scopes above.
+3. On the OAuth client, add these redirect URIs:
+   - `https://<junior host>/api/plugins/google/oauth/callback`
+   - `http://127.0.0.1:8765/oauth/callback`, for the CLI. Use another port with
+     `junior google connect --port`.
+4. Give the Junior account a Workspace license.
+5. Set these environment variables on the deployment:
+
+| Variable                           | Purpose                                         |
+| ---------------------------------- | ----------------------------------------------- |
+| `GOOGLE_CLIENT_ID`                 | OAuth client id, shared with dashboard sign-in  |
+| `GOOGLE_CLIENT_SECRET`             | OAuth client secret                             |
+| `GOOGLE_WORKSPACE_ACCOUNT_EMAIL`   | The account Junior acts as                      |
+| `GOOGLE_WORKSPACE_ALLOWED_DOMAINS` | Optional comma-separated domains to schedule in |
+
+The plugin registers no tools and no sign-in routes until the first three
+variables are set. The Admin page shows **Not configured** until then.
+
+6. Run `junior upgrade` to create the table.
+7. Run `junior admin grant <email>` for each person who may connect the account.
+8. Connect the account on **Admin → Google account**, or run
+   `junior google connect` with the deployment database configured.
+
+## Known gaps
+
+- The refresh token is stored in plain text in Postgres. Encryption at rest is
+  tracked in getsentry/junior#2065.
+- Free/busy and event details show only what the company's calendar sharing
+  default allows. Calendars that Junior cannot see appear in `unavailable`
+  for `findMeetingTimes`, and as `visible: false` for `listCalendarEvents`.
+- Anyone who can talk to Junior can ask it to read a colleague's calendar.
+  Junior returns what its own account can see, so set the sharing default
+  with that in mind.
+- No disconnect command. To revoke access, remove the app grant from the
+  Junior account in Google.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import type { PluginCliCommandDefinition } from "@sentry/junior-plugin-api";
+/** Create the plugin-owned `google` admin CLI command. */
+export declare function createGoogleCliCommand(): PluginCliCommandDefinition;

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Deployment configuration for the Google plugin.
+ *
+ * Values come from host environment variables. They never reach the sandbox.
+ */
+/** Dashboard sign-in uses the same OAuth client. */
+export declare const GOOGLE_CLIENT_ID_ENV = "GOOGLE_CLIENT_ID";
+export declare const GOOGLE_CLIENT_SECRET_ENV = "GOOGLE_CLIENT_SECRET";
+export declare const GOOGLE_ACCOUNT_EMAIL_ENV = "GOOGLE_WORKSPACE_ACCOUNT_EMAIL";
+export declare const GOOGLE_ALLOWED_DOMAINS_ENV = "GOOGLE_WORKSPACE_ALLOWED_DOMAINS";
+/**
+ * Scopes the Calendar tools need. Request nothing broader.
+ *
+ * - `calendar.events.freebusy`: availability for `findMeetingTimes`.
+ * - `calendar.events.readonly`: events that Junior's account can see on other
+ *   people's calendars, for `listCalendarEvents`. Google sharing settings
+ *   still decide how much detail each calendar shows.
+ * - `calendar.events.owned`: create and change events on Junior's own
+ *   calendar.
+ */
+export declare const GOOGLE_CALENDAR_SCOPES: readonly ["https://www.googleapis.com/auth/calendar.events.freebusy", "https://www.googleapis.com/auth/calendar.events.owned", "https://www.googleapis.com/auth/calendar.events.readonly"];
+/** Identity scopes used only to verify which account signed in. */
+export declare const GOOGLE_IDENTITY_SCOPES: readonly ["openid", "email"];
+export interface GoogleConfig {
+    /** The Workspace account Junior acts as, for example `junior@sentry.io`. */
+    accountEmail: string;
+    /** Domains Junior may check availability for and invite. */
+    allowedDomains: string[];
+    clientId: string;
+    clientSecret: string;
+}
+/** Return the email domain in lowercase, or undefined for a malformed email. */
+export declare function emailDomain(email: string): string | undefined;
+/**
+ * Read the Google plugin configuration, or undefined when the deployment does
+ * not configure the plugin.
+ */
+export declare function readGoogleConfig(): GoogleConfig | undefined;

package/dist/credentials.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Credential issuing and egress policy for Google APIs.
+ *
+ * Only this plugin's own tools may use Junior's Google account. The tools
+ * enforce disclosure and invite rules in code, so the sandbox and other
+ * callers get no Google credential at all.
+ */
+import { type EgressHookContext, type IssueCredentialHookContext, type PluginCredentialResult, type PluginGrant } from "@sentry/junior-plugin-api";
+export declare const GOOGLE_API_DOMAIN = "www.googleapis.com";
+/** Google API operations that plugin tools may perform. */
+export declare const GOOGLE_OPERATIONS: {
+    readonly "google.calendar.event.create": {
+        readonly access: "write";
+        readonly method: "POST";
+        readonly path: RegExp;
+    };
+    readonly "google.calendar.event.get": {
+        readonly access: "read";
+        readonly method: "GET";
+        readonly path: RegExp;
+    };
+    readonly "google.calendar.event.update": {
+        readonly access: "write";
+        readonly method: "PATCH";
+        readonly path: RegExp;
+    };
+    readonly "google.calendar.events.list": {
+        readonly access: "read";
+        readonly method: "GET";
+        readonly path: RegExp;
+    };
+    readonly "google.calendar.freebusy.query": {
+        readonly access: "read";
+        readonly method: "POST";
+        readonly path: RegExp;
+    };
+};
+export type GoogleOperation = keyof typeof GOOGLE_OPERATIONS;
+/** Select the grant for one Google request, or deny it. */
+export declare function googleGrantForEgress(ctx: EgressHookContext): PluginGrant;
+/** Mint a short-lived access token for Junior's Google account. */
+export declare function issueGoogleCredential(ctx: IssueCredentialHookContext): Promise<PluginCredentialResult>;

package/dist/db/schema.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Google accounts that Junior acts as.
+ *
+ * One row per connected account email. The refresh token is a long-lived
+ * secret: never log it, return it from routes, or expose it to the sandbox.
+ */
+export declare const juniorGoogleAccounts: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "junior_google_accounts";
+    schema: undefined;
+    columns: {
+        accountEmail: import("drizzle-orm/pg-core").PgColumn<{
+            name: "account_email";
+            tableName: "junior_google_accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        refreshToken: import("drizzle-orm/pg-core").PgColumn<{
+            name: "refresh_token";
+            tableName: "junior_google_accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        scope: import("drizzle-orm/pg-core").PgColumn<{
+            name: "scope";
+            tableName: "junior_google_accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        connectedBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "connected_by";
+            tableName: "junior_google_accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        connectedAtMs: import("drizzle-orm/pg-core").PgColumn<{
+            name: "connected_at_ms";
+            tableName: "junior_google_accounts";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Google plugin runtime boundary.
+ *
+ * Junior acts as its own Google Workspace account. A Junior admin connects
+ * that account out of band, through the dashboard Admin page or the CLI. Calendar
+ * tools use host-owned egress, and the sandbox gets no Google credential.
+ */
+import { type PluginRegistration } from "@sentry/junior-plugin-api";
+/** Register Junior's Google Workspace plugin. */
+export declare function googlePlugin(): PluginRegistration;