SAS (Shared Access Signature) Generation

/**
 * Generates an account-level SAS token for accessing multiple services and resources
 * @param credential - Named key credential for signing the SAS
 * @param options - Configuration options for the account SAS
 * @returns SAS query string
 */
function generateAccountSas(credential: NamedKeyCredential, options?: AccountSasOptions): string;

/**
 * Generates a table-level SAS token for accessing a specific table
 * @param tableName - Name of the table to grant access to
 * @param credential - Named key credential for signing the SAS
 * @param options - Configuration options for the table SAS
 * @returns SAS query string
 */
function generateTableSas(tableName: string, credential: NamedKeyCredential, options?: TableSasSignatureValues): string;

/**
 * Options to configure generateAccountSas operation.
 */
interface AccountSasOptions {
  /** The time at which the shared access signature becomes invalid. Default to an hour later if not provided. */
  expiresOn?: Date;
  /** Specifies the list of permissions to be associated with the SAS. */
  permissions?: AccountSasPermissions;
  /** Specifies the resource types associated with the shared access signature. */
  resourceTypes?: string;
  /** The version of the service this SAS will target. If not specified, it will default to the version targeted by the library. */
  version?: string;
  /** SAS protocols allowed. */
  protocol?: SasProtocol;
  /** When the SAS will take effect. */
  startsOn?: Date;
  /** IP range allowed. */
  ipRange?: SasIPRange;
  /** Account services */
  services?: AccountSasServices;
}

/**
 * Services that the SAS token can access
 */
interface AccountSasServices {
  /** Permission to access blob resources granted. */
  blob?: boolean;
  /** Permission to access file resources granted. */
  file?: boolean;
  /** Permission to access queue resources granted. */
  queue?: boolean;
  /** Permission to access table resources granted. */
  table?: boolean;
}

/**
 * Represents the Resources that are accessible by the SAS token
 */
interface AccountSasResourceTypes {
  /** Permission to access service level APIs granted. */
  service?: boolean;
  /** Permission to access container level APIs (Blob Containers, Tables, Queues, File Shares) granted. */
  container?: boolean;
  /** Permission to access object level APIs (Blobs, Table Entities, Queue Messages, Files) granted. */
  object?: boolean;
}

/**
 * A type that looks like an account SAS permission.
 */
interface AccountSasPermissions {
  /** Grants permission to list entities. */
  query?: boolean;
  /** Grants permission to create tables */
  write?: boolean;
  /** Grants permission to delete tables and entities */
  delete?: boolean;
  /** Grants permission to list tables */
  list?: boolean;
  /** Grants permission to create entities */
  add?: boolean;
  /** Permissions to update messages and table entities granted. */
  update?: boolean;
}

/**
 * TableSASSignatureValues is used to help generating Table service SAS tokens for tables
 */
interface TableSasSignatureValues {
  /** The version of the service this SAS will target. If not specified, it will default to the version targeted by the library. */
  version?: string;
  /** Optional. SAS protocols, HTTPS only or HTTPSandHTTP */
  protocol?: SasProtocol;
  /** Optional. When the SAS will take effect. */
  startsOn?: Date;
  /** Optional only when identifier is provided. The time after which the SAS will no longer work. */
  expiresOn?: Date;
  /** Optional only when identifier is provided. Please refer to TableSasPermissions for help constructing the permissions string. */
  permissions?: TableSasPermissions;
  /** Optional. IP ranges allowed in this SAS. */
  ipRange?: SasIPRange;
  /** Optional. The name of the access policy on the container this SAS references if any. */
  identifier?: string;
  /** Define the start of a Partition Key range */
  startPartitionKey?: string;
  /** Define the end of a Partition Key range */
  endPartitionKey?: string;
  /** Define the start of a Row Key range */
  startRowKey?: string;
  /** Define the end of a Row Key range */
  endRowKey?: string;
}

/**
 * A type that looks like a Table SAS permission.
 */
interface TableSasPermissions {
  /** Specifies Query access granted. */
  query?: boolean;
  /** Specifies Add access granted. */
  add?: boolean;
  /** Specifies Update access granted. */
  update?: boolean;
  /** Specifies Delete access granted. */
  delete?: boolean;
}

/**
 * IP address range for SAS restrictions
 */
interface SasIPRange {
  /** Starting IP address */
  start: string;
  /** Ending IP address (optional for single IP) */
  end?: string;
}

/**
 * Allowed protocols for SAS access
 */
type SasProtocol = "https" | "https,http";

/**
 * Immutable representation of SAS query parameters
 */
interface SasQueryParameters {
  /** SAS version */
  version: string;
  /** Services accessible */
  services?: string;
  /** Resource types accessible */
  resourceTypes?: string;
  /** Protocol restriction */
  protocol?: SasProtocol;
  /** Start time */
  startsOn?: Date;
  /** Expiry time */
  expiresOn?: Date;
  /** IP range restriction */
  ipRange?: SasIPRange;
  /** Permissions */
  permissions?: string;
  /** Signature */
  signature?: string;
  /** Stored access policy identifier */
  identifier?: string;
  /** Resource name */
  resource?: string;
}

/**
 * Options for constructing SAS query parameters
 */
interface SasQueryParametersOptions {
  /** SAS version */
  version: string;
  /** Protocol restriction */
  protocol?: SasProtocol;
  /** Start time */
  startsOn?: Date;
  /** Expiry time */
  expiresOn?: Date;
  /** Permissions */
  permissions?: string;
  /** Services */
  services?: string;
  /** Resource types */
  resourceTypes?: string;
  /** IP range */
  ipRange?: SasIPRange;
  /** Signature */
  signature?: string;
  /** Stored access policy identifier */
  identifier?: string;
  /** Resource */
  resource?: string;
}

/**
 * User delegation key properties for Azure AD SAS
 */
interface UserDelegationKey {
  /** Signed object ID */
  signedObjectId: string;
  /** Signed tenant ID */
  signedTenantId: string;
  /** Signed start time */
  signedStartsOn: Date;
  /** Signed expiry time */
  signedExpiresOn: Date;
  /** Signed service */
  signedService: string;
  /** Signed version */
  signedVersion: string;
  /** Key value */
  value: string;
}

/**
 * Parse account SAS permissions from string
 * @param permissions - Permission string (e.g., "rwdlau")
 * @returns AccountSasPermissions object
 */
function accountSasPermissionsFromString(permissions: string): AccountSasPermissions;

/**
 * Convert account SAS permissions to string
 * @param permissions - AccountSasPermissions object
 * @returns Permission string
 */
function accountSasPermissionsToString(permissions: AccountSasPermissions): string;

/**
 * Parse account SAS services from string
 * @param services - Services string (e.g., "btqf")
 * @returns AccountSasServices object
 */
function accountSasServicesFromString(services: string): AccountSasServices;

/**
 * Convert account SAS services to string
 * @param services - AccountSasServices object (optional)
 * @returns Services string
 */
function accountSasServicesToString(services?: AccountSasServices): string;

/**
 * Parse table SAS permissions from string
 * @param permissions - Permission string (e.g., "raud") 
 * @returns TableSasPermissions object
 */
function tableSasPermissionsFromString(permissions: string): TableSasPermissions;

/**
 * Convert table SAS permissions to string
 * @param permissions - TableSasPermissions object (optional)
 * @returns Permission string
 */
function tableSasPermissionsToString(permissions?: TableSasPermissions): string;

/**
 * Convert IP range to string representation
 * @param ipRange - SasIPRange object (optional)
 * @returns IP range string
 */
function ipRangeToString(ipRange?: SasIPRange): string;

import { 
  generateAccountSas, 
  generateTableSas, 
  AzureNamedKeyCredential,
  accountSasPermissionsFromString,
  tableSasPermissionsFromString
} from "@azure/data-tables";

const credential = new AzureNamedKeyCredential("accountName", "accountKey");

// Generate account-level SAS for table service access
const accountSas = generateAccountSas(credential, {
  services: {
    blob: false,
    file: false, 
    queue: false,
    table: true
  },
  resourceTypes: {
    service: true,
    container: true,
    object: true
  },
  permissions: {
    query: true,
    write: true,
    delete: false,
    list: true,
    add: true,
    update: true
  },
  expiresOn: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
  ipRange: {
    start: "192.168.1.0",
    end: "192.168.1.255"
  },
  protocol: "https"
});

console.log(`Account SAS: ${accountSas}`);

// Generate table-specific SAS with partition/row key ranges  
const tableSas = generateTableSas("Customers", credential, {
  permissions: {
    query: true,
    add: true,
    update: true,
    delete: false
  },
  expiresOn: new Date(Date.now() + 2 * 60 * 60 * 1000), // 2 hours
  startsOn: new Date(),
  startPartitionKey: "A",
  endPartitionKey: "M",
  protocol: "https"
});

console.log(`Table SAS: ${tableSas}`);

// Using permission helper functions
const permissions = accountSasPermissionsFromString("rlau"); 
// Results in: { query: true, list: true, add: true, update: true, write: false, delete: false }

const tablePermissions = tableSasPermissionsFromString("raud");
// Results in: { query: true, add: true, update: true, delete: true }

// Generate SAS using parsed permissions
const simpleSas = generateTableSas("Products", credential, {
  permissions: tablePermissions,
  expiresOn: new Date(Date.now() + 60 * 60 * 1000) // 1 hour
});

// Use stored access policy instead of embedding permissions
const policyBasedSas = generateTableSas("Orders", credential, {
  identifier: "read-only-policy", // References stored policy
  expiresOn: new Date(Date.now() + 12 * 60 * 60 * 1000) // 12 hours
});

// The permissions come from the stored access policy on the table

// Single IP restriction
const restrictedSas = generateTableSas("SensitiveData", credential, {
  permissions: { query: true, add: false, update: false, delete: false },
  expiresOn: new Date(Date.now() + 30 * 60 * 1000), // 30 minutes
  ipRange: { start: "203.0.113.1" } // Single IP
});

// IP range restriction
const rangeSas = generateTableSas("PublicData", credential, {
  permissions: { query: true, add: true, update: true, delete: true },
  expiresOn: new Date(Date.now() + 6 * 60 * 60 * 1000), // 6 hours
  ipRange: { start: "10.0.0.0", end: "10.255.255.255" } // Private network range
});

// Restrict access to specific partition and row key ranges
const rangeLimitedSas = generateTableSas("CustomerOrders", credential, {
  permissions: { query: true, add: true, update: true, delete: false },
  expiresOn: new Date(Date.now() + 4 * 60 * 60 * 1000), // 4 hours
  startPartitionKey: "2023-Q1", // Start of range
  endPartitionKey: "2023-Q2",   // End of range
  startRowKey: "order-1000",    // Minimum row key
  endRowKey: "order-9999"       // Maximum row key
});

// This SAS only allows access to entities within the specified ranges

import { TableClient, AzureSASCredential } from "@azure/data-tables";

// Use generated SAS with client
const sasCredential = new AzureSASCredential(tableSas);
const tableClient = new TableClient(
  "https://myaccount.table.core.windows.net",
  "Customers",
  sasCredential
);

// Client operations are now limited by SAS permissions and constraints
const entities = tableClient.listEntities({
  queryOptions: { top: 100 }
});

for await (const entity of entities) {
  console.log(entity);
}

type NamedKeyCredential = AzureNamedKeyCredential;

interface AzureNamedKeyCredential {
  /** Account name */
  name: string;
  /** Account key */
  key: string;
}

interface AzureSASCredential {
  /** SAS signature string */
  signature: string;
}