(core) add an access token mechanism to help with attachments in custom widgets

Summary:
With this, a custom widget can render an attachment by doing:
```
const tokenInfo = await grist.docApi.getAccessToken({readOnly: true});
const img = document.getElementById('the_image');
const id = record.C[0];  // get an id of an attachment
const src = `${tokenInfo.baseUrl}/attachments/${id}/download?auth=${tokenInfo.token}`;
img.setAttribute('src', src)
```

The access token expires after a few mins, so if a user right-clicks on an image
to save it, they may get access denied unless they refresh the page. A little awkward,
but s3 pre-authorized links behave similarly and it generally isn't a deal-breaker.

Test Plan: added tests

Reviewers: dsagal

Reviewed By: dsagal

Subscribers: dsagal

Differential Revision: https://phab.getgrist.com/D3488

app/plugin/GristAPI-ti.ts

@@ -18,6 +18,7 @@ export const GristDocAPI = t.iface([], {
   "listTables": t.func(t.array("string")),
   "fetchTable": t.func("any", t.param("tableId", "string")),
   "applyUserActions": t.func("any", t.param("actions", t.array(t.array("any"))), t.param("options", "any", true)),
+  "getAccessToken": t.func("AccessTokenResult", t.param("options", "AccessTokenOptions")),
 });
 
 export const GristView = t.iface([], {
@@ -27,10 +28,22 @@ export const GristView = t.iface([], {
   "setSelectedRows": t.func("void", t.param("rowIds", t.array("number"))),
 });
 
+export const AccessTokenOptions = t.iface([], {
+  "readOnly": t.opt("boolean"),
+});
+
+export const AccessTokenResult = t.iface([], {
+  "token": "string",
+  "baseUrl": "string",
+  "ttlMsecs": "number",
+});
+
 const exportedTypeSuite: t.ITypeSuite = {
   ComponentKind,
   GristAPI,
   GristDocAPI,
   GristView,
+  AccessTokenOptions,
+  AccessTokenResult,
 };
 export default exportedTypeSuite;

app/plugin/GristAPI.ts

@@ -97,6 +97,11 @@ export interface GristDocAPI {
   applyUserActions(actions: any[][], options?: any): Promise<any>;
   // TODO: return type should be Promise<ApplyUAResult>, but this requires importing
   // modules from `app/common` which is not currently supported by the build.
+
+  /**
+   * Get a token for out-of-band access to the document.
+   */
+  getAccessToken(options: AccessTokenOptions): Promise<AccessTokenResult>;
 }
 
 /**
@@ -127,3 +132,13 @@ export interface GristView {
    */
   setSelectedRows(rowIds: number[]): Promise<void>;
 }
+
+export interface AccessTokenOptions {
+  readOnly?: boolean;   // restrict use of token to reading.
+}
+
+export interface AccessTokenResult {
+  token: string;        // token string
+  baseUrl: string;      // url of document api, like https://..../api/docs/DOCID
+  ttlMsecs: number;     // number of milliseconds token will be valid for (typically several minutes)
+}

app/plugin/grist-plugin-api.ts

@@ -20,7 +20,8 @@
 
 import { ColumnsToMap, CustomSectionAPI, InteractionOptions, InteractionOptionsRequest,
          WidgetColumnMap } from './CustomSectionAPI';
-import { GristAPI, GristDocAPI, GristView, RPC_GRISTAPI_INTERFACE } from './GristAPI';
+import { AccessTokenOptions, AccessTokenResult, GristAPI, GristDocAPI,
+         GristView, RPC_GRISTAPI_INTERFACE } from './GristAPI';
 import { RowRecord } from './GristData';
 import { ImportSource, ImportSourceAPI, InternalImportSourceAPI } from './InternalImportSourceAPI';
 import { decodeObject, mapValues } from './objtypes';
@@ -158,6 +159,14 @@ export function getTable(tableId?: string): TableOperations {
   }, {});
 }
 
+/**
+ * Get an access token, for making API calls outside of the custom widget
+ * API. There is no caching of tokens.
+ */
+export async function getAccessToken(options?: AccessTokenOptions): Promise<AccessTokenResult> {
+  return docApi.getAccessToken(options || {});
+}
+
 /**
  * Get the current selected table (for custom widgets).
  */